Sommaire

BONJOUR
Musique "Invention BWV988" J.S. BACH 1685-1750

Tutoriel et Help

Library SDL


SDL_image 1.2.8: Table of Contents

[Top] [Contents] [Index] [ ? ]

Table of Contents

    1. Overview
    2. Getting Started
      2.1 Includes
      2.2 Compiling
    3. Functions
      3.1 General
        3.1.1 IMG_Linked_Version
        3.1.2 IMG_Init
        3.1.3 IMG_Quit
      3.2 Loading
        3.2.1 IMG_Load
        3.2.2 IMG_Load_RW
        3.2.3 IMG_LoadTyped_RW
        3.2.4 IMG_LoadCUR_RW
        3.2.5 IMG_LoadICO_RW
        3.2.6 IMG_LoadBMP_RW
        3.2.7 IMG_LoadPNM_RW
        3.2.8 IMG_LoadXPM_RW
        3.2.9 IMG_LoadXCF_RW
        3.2.10 IMG_LoadPCX_RW
        3.2.11 IMG_LoadGIF_RW
        3.2.12 IMG_LoadJPG_RW
        3.2.13 IMG_LoadTIF_RW
        3.2.14 IMG_LoadPNG_RW
        3.2.15 IMG_LoadTGA_RW
        3.2.16 IMG_LoadLBM_RW
        3.2.17 IMG_LoadXV_RW
        3.2.18 IMG_ReadXPMFromArray
      3.3 Info
        3.3.1 IMG_isCUR
        3.3.2 IMG_isICO
        3.3.3 IMG_isBMP
        3.3.4 IMG_isPNM
        3.3.5 IMG_isXPM
        3.3.6 IMG_isXCF
        3.3.7 IMG_isPCX
        3.3.8 IMG_isGIF
        3.3.9 IMG_isJPG
        3.3.10 IMG_isTIF
        3.3.11 IMG_isPNG
        3.3.12 IMG_isLBM
        3.3.13 IMG_isXV
      3.4 Errors
        3.4.1 IMG_SetError
        3.4.2 IMG_GetError
    4. Defines
    Index

This document was generated on November, 3 2009 using texi2html


SDL_mixer 1.2.10: Table of Contents

[Top] [Contents] [Index] [ ? ]

Table of Contents

    1. Overview
    2. Getting Started
      2.1 Includes
      2.2 Compiling
    3. Conflicts
    4. Functions
      4.1 General
        4.1.1 Mix_Linked_Version
        4.1.2 Mix_Init
        4.1.3 Mix_Quit
        4.1.4 Mix_OpenAudio
        4.1.5 Mix_CloseAudio
        4.1.6 Mix_SetError
        4.1.7 Mix_GetError
        4.1.8 Mix_QuerySpec
      4.2 Samples
        4.2.1 Mix_GetNumChunkDecoders
        4.2.2 Mix_GetChunkDecoder
        4.2.3 Mix_LoadWAV
        4.2.4 Mix_LoadWAV_RW
        4.2.5 Mix_QuickLoad_WAV
        4.2.6 Mix_QuickLoad_RAW
        4.2.7 Mix_VolumeChunk
        4.2.8 Mix_FreeChunk
      4.3 Channels
        4.3.1 Mix_AllocateChannels
        4.3.2 Mix_Volume
        4.3.3 Mix_PlayChannel
        4.3.4 Mix_PlayChannelTimed
        4.3.5 Mix_FadeInChannel
        4.3.6 Mix_FadeInChannelTimed
        4.3.7 Mix_Pause
        4.3.8 Mix_Resume
        4.3.9 Mix_HaltChannel
        4.3.10 Mix_ExpireChannel
        4.3.11 Mix_FadeOutChannel
        4.3.12 Mix_ChannelFinished
        4.3.13 Mix_Playing
        4.3.14 Mix_Paused
        4.3.15 Mix_FadingChannel
        4.3.16 Mix_GetChunk
      4.4 Groups
        4.4.1 Mix_ReserveChannels
        4.4.2 Mix_GroupChannel
        4.4.3 Mix_GroupChannels
        4.4.4 Mix_GroupCount
        4.4.5 Mix_GroupAvailable
        4.4.6 Mix_GroupOldest
        4.4.7 Mix_GroupNewer
        4.4.8 Mix_FadeOutGroup
        4.4.9 Mix_HaltGroup
      4.5 Music
        4.5.1 Mix_GetNumMusicDecoders
        4.5.2 Mix_GetMusicDecoder
        4.5.3 Mix_LoadMUS
        4.5.4 Mix_FreeMusic
        4.5.5 Mix_PlayMusic
        4.5.6 Mix_FadeInMusic
        4.5.7 Mix_FadeInMusicPos
        4.5.8 Mix_HookMusic
        4.5.9 Mix_VolumeMusic
        4.5.10 Mix_PauseMusic
        4.5.11 Mix_ResumeMusic
        4.5.12 Mix_RewindMusic
        4.5.13 Mix_SetMusicPosition
        4.5.14 Mix_SetMusicCMD
        4.5.15 Mix_HaltMusic
        4.5.16 Mix_FadeOutMusic
        4.5.17 Mix_HookMusicFinished
        4.5.18 Mix_GetMusicType
        4.5.19 Mix_PlayingMusic
        4.5.20 Mix_PausedMusic
        4.5.21 Mix_FadingMusic
        4.5.22 Mix_GetMusicHookData
      4.6 Effects
        4.6.1 Mix_RegisterEffect
        4.6.2 Mix_UnregisterEffect
        4.6.3 Mix_UnregisterAllEffects
        4.6.4 Mix_SetPostMix
        4.6.5 Mix_SetPanning
        4.6.6 Mix_SetDistance
        4.6.7 Mix_SetPosition
        4.6.8 Mix_SetReverseStereo
    5. Types
      5.1 Mix_Chunk
      5.2 Mix_Music
      5.3 Mix_MusicType
      5.4 Mix_Fading
      5.5 Mix_EffectFunc_t
      5.6 Mix_EffectDone_t
    6. Defines
    7. Glossary
    Index

This document was generated on November, 13 2009 using texi2html


SDL_net 1.2.7: Table of Contents

[Top] [Contents] [Index] [ ? ]

Table of Contents

    1. Overview
    2. Getting Started
      2.1 Includes
      2.2 Compiling
    3. Functions
      3.1 General
        3.1.1 SDLNet_Linked_Version
        3.1.2 SDLNet_Init
        3.1.3 SDLNet_Quit
        3.1.4 SDLNet_GetError
        3.1.5 SDLNet_Write16
        3.1.6 SDLNet_Write32
        3.1.7 SDLNet_Read16
        3.1.8 SDLNet_Read32
      3.2 Name Resolution
        3.2.1 SDLNet_ResolveHost
        3.2.2 SDLNet_ResolveIP
      3.3 TCP Sockets
        3.3.1 SDLNet_TCP_Open
        3.3.2 SDLNet_TCP_Close
        3.3.3 SDLNet_TCP_Accept
        3.3.4 SDLNet_TCP_GetPeerAddress
        3.3.5 SDLNet_TCP_Send
        3.3.6 SDLNet_TCP_Recv
      3.4 UDP Sockets
        3.4.1 SDLNet_UDP_Open
        3.4.2 SDLNet_UDP_Close
        3.4.3 SDLNet_UDP_Bind
        3.4.4 SDLNet_UDP_Unbind
        3.4.5 SDLNet_UDP_GetPeerAddress
        3.4.6 SDLNet_UDP_Send
        3.4.7 SDLNet_UDP_Recv
        3.4.8 SDLNet_UDP_SendV
        3.4.9 SDLNet_UDP_RecvV
      3.5 UDP Packets
        3.5.1 SDLNet_AllocPacket
        3.5.2 SDLNet_ResizePacket
        3.5.3 SDLNet_FreePacket
        3.5.4 SDLNet_AllocPacketV
        3.5.5 SDLNet_FreePacketV
      3.6 Socket Sets
        3.6.1 SDLNet_AllocSocketSet
        3.6.2 SDLNet_FreeSocketSet
        3.6.3 SDLNet_AddSocket
        3.6.4 SDLNet_DelSocket
        3.6.5 SDLNet_CheckSockets
        3.6.6 SDLNet_SocketReady
    4. Types
      4.1 IPaddress
      4.2 TCPsocket
      4.3 UDPsocket
      4.4 UDPpacket
      4.5 SDLNet_SocketSet
      4.6 SDLNet_GenericSocket
    5. Defines
    6. Glossary
    Index

This document was generated on November, 3 2009 using texi2html


SDL_ttf 2.0.10: Table of Contents

[Top] [Contents] [Index] [ ? ]

Table of Contents

    1. Overview
    2. Getting Started
      2.1 Includes
      2.2 Compiling
    3. Functions
      3.1 General
        3.1.1 TTF_Linked_Version
        3.1.2 TTF_Init
        3.1.3 TTF_WasInit
        3.1.4 TTF_Quit
        3.1.5 TTF_SetError
        3.1.6 TTF_GetError
      3.2 Management
        3.2.1 TTF_OpenFont
        3.2.2 TTF_OpenFontRW
        3.2.3 TTF_OpenFontIndex
        3.2.4 TTF_OpenFontIndexRW
        3.2.5 TTF_CloseFont
      3.3 Attributes
        3.3.1 TTF_ByteSwappedUNICODE
        3.3.2 TTF_GetFontStyle
        3.3.3 TTF_SetFontStyle
        3.3.4 TTF_GetFontOutline
        3.3.5 TTF_SetFontOutline
        3.3.6 TTF_GetFontHinting
        3.3.7 TTF_SetFontHinting
        3.3.8 TTF_GetFontKerning
        3.3.9 TTF_SetFontKerning
        3.3.10 TTF_FontHeight
        3.3.11 TTF_FontAscent
        3.3.12 TTF_FontDescent
        3.3.13 TTF_FontLineSkip
        3.3.14 TTF_FontFaces
        3.3.15 TTF_FontFaceIsFixedWidth
        3.3.16 TTF_FontFaceFamilyName
        3.3.17 TTF_FontFaceStyleName
        3.3.18 TTF_GlyphIsProvided
        3.3.19 TTF_GlyphMetrics
        3.3.20 TTF_SizeText
        3.3.21 TTF_SizeUTF8
        3.3.22 TTF_SizeUNICODE
      3.4 Render
        3.4.1 TTF_RenderText_Solid
        3.4.2 TTF_RenderUTF8_Solid
        3.4.3 TTF_RenderUNICODE_Solid
        3.4.4 TTF_RenderGlyph_Solid
        3.4.5 TTF_RenderText_Shaded
        3.4.6 TTF_RenderUTF8_Shaded
        3.4.7 TTF_RenderUNICODE_Shaded
        3.4.8 TTF_RenderGlyph_Shaded
        3.4.9 TTF_RenderText_Blended
        3.4.10 TTF_RenderUTF8_Blended
        3.4.11 TTF_RenderUNICODE_Blended
        3.4.12 TTF_RenderGlyph_Blended
    4. Types
      4.1 TTF_Font
    5. Defines
    6. Glossary
    Index

This document was generated on November, 13 2009 using texi2html


SDL_image 1.2.8

1. Overview The README from the SDL_image distribution

2. Getting Started Using SDL_image

3. Functions | Functions supported by the SDL_image API
4. Defines | Defined values/macros in the SDL_image API

Index Index of selected words
[ < ] [ > ] [ << ] [ Up ] [ >> ]

1. Overview

A Little Bit About Me

I am currently, as I write this document, a programmer for Raytheon. There I do all sorts of communications, network, GUI, and other general programming tasks in C/C++ on the Solaris, Linux, and Windows Operating Systems.

Feel free to contact me: JonathanCAtkins@gmail.com

I am also usually on IRC at irc.freenode.net in the #SDL channel as LIM

Why is this for you?

Images provide the basic visual building blocks for any user interface. Colors and fun shapes are the stuff that we as kids looked at for hours at a time while trying to shoot down big aliens and rescue pixelated princesses. Now it's our turn to make the images that others will remember later in life perhaps. Now how do we get this dang images into our SDL programs, and be flexible in the handling of the images so that we don't even have to worry about what various formats they may be in? This is where SDLimage makes all of our lives easier. This document doesn't help you make artwork, but it will give you the functional knowledge on how to get that art into your game. Now go forth and make your Stick Figure of Justice, someone else might fill in for your lack of artistry, at least you won't have to make much of an effort to include the new and better art into your code.

This is the README, updated by me for accuracy, in the SDL_image source archive.

SDL_image 1.2

The latest version of this library is available from:
SDL_image Homepage

This is a simple library to load images of various formats as SDL surfaces.
This library supports ICO(Icon)/CUR(Cursor)/BMP, PNM (PPM/PGM/PBM), XPM,
LBM(IFF ILBM), PCX, GIF, JPEG, PNG, TGA, TIFF, and XV thumbnail formats.

API:
#include "SDL_image.h"

    SDL_Surface *IMG_Load(const char *file);
or
    SDL_Surface *IMG_Load_RW(SDL_RWops *src, int freesrc);
or
    SDL_Surface *IMG_LoadTyped_RW(SDL_RWops *src, int freesrc, char *type);

where type is a string specifying the format (i.e. "PNG" or "pcx").
Note that IMG_Load_RW cannot load TGA images.

To create a surface from an XPM image included in C source, use:

    SDL_Surface *IMG_ReadXPMFromArray(char **xpm);

An example program 'showimage' is included, with source in showimage.c

JPEG support requires the JPEG library:
    IJG Homepage
PNG support requires the PNG library:
    PNG Homepage
  and the Zlib library:
    Zlib Homepage
TIFF support requires the TIFF library:
    SGI TIFF FTP Site

If you have these libraries installed in non-standard places, you can
try adding those paths to the configure script, e.g.
sh ./configure CPPFLAGS="-I/somewhere/include" LDFLAGS="-L/somewhere/lib"
If this works, you may need to add /somewhere/lib to your LD_LIBRARY_PATH
so shared library loading works correctly.

This library is under the GNU Library General Public License, see the file
"COPYING" for details.  Certain image loaders may be under a different
license, see the individual image loader source files for details.

[ < ] [ > ] [ << ] [ Up ] [ >> ]

2. Getting Started

This assumes you have gotten SDL_image and installed it on your system. SDL_image has an README document in the source distribution to help you get it compiled and installed. Well it at least points you to locations for the source code of some of the image libraries SDL_image can use. Most of the other image formats are builtin to SDL_image.

Generally, in UNIX-like environments, installation consists of:

./configure
make
make install

SDL_image supports loading and decoding images from the following formats:

TGA
TrueVision Targa (MUST have .tga)
BMP
Windows Bitmap(.bmp)
PNM
Portable Anymap (.pnm)
.pbm = Portable BitMap (mono)
.pgm = Portable GreyMap (256 greys)
.ppm = Portable PixMap (full color)
XPM
X11 Pixmap (.xpm) can be #included directly in code
This is NOT the same as XBM(X11 Bitmap) format, which is for monocolor images.
XCF
GIMP native (.xcf) (XCF = eXperimental Computing Facility?)
This format is always changing, and since there's no library supplied by the GIMP project to load XCF, the loader may frequently fail to load much of any image from an XCF file. It's better to load this in GIMP and convert to a better supported image format.
PCX
ZSoft IBM PC Paintbrush (.pcx)
GIF
CompuServe Graphics Interchange Format (.gif)
JPG
Joint Photographic Experts Group JFIF format (.jpg or .jpeg)
TIF
Tagged Image File Format (.tif or .tiff)
LBM
Interleaved Bitmap (.lbm or .iff) FORM : ILBM or PBM(packed bitmap)
HAM6, HAM8, and 24bit types are not supported.
PNG
Portable Network Graphics (.png)

You may also want to look at some demonstration code which may be downloaded from:
http://www.jonatkins.org/SDL_image/

2.1 Includes | The include files to use for SDL_image
2.2 Compiling | Using the SDL_image library and header file.

[ < ] [ > ] [ << ] [ Up ] [ >> ]

2.1 Includes

To use SDL_image functions in a C/C++ source code file, you must use the SDL_image.h include file:

#include "SDL_image.h"

[ < ] [ > ] [ << ] [ Up ] [ >> ]

2.2 Compiling

To link with SDL_image you should use sdl-config to get the required SDL compilation options. After that, compiling with SDL_image is quite easy.
Note: Some systems may not have the SDL_image library and include file in the same place as the SDL library and includes are located, in that case you will need to add more -I and -L paths to these command lines.

Simple Example for compiling an object file:

cc -c `sdl-config --cflags` mysource.c

Simple Example for compiling an object file:

cc -o myprogram mysource.o `sdl-config --libs` -lSDL_image

Now myprogram is ready to run.

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3. Functions

These are the functions in the SDL_image API.

3.1 General | Versioning, Initialization and Cleanup
3.2 Loading | From Image Data to SDL_Surface
3.3 Info | Image Type Detection
3.4 Errors | Error Handling

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.1 General

These functions query, initialize, and cleanup the SDL_image library.

3.1.1 IMG_Linked_Version | Get version number
3.1.2 IMG_Init | Initialize SDL_image
3.1.3 IMG_Quit | Cleanup SDL_image

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.1.1 IMG_Linked_Version

const SDL_version *IMG_Linked_Version()
void SDL_IMAGE_VERSION(SDL_version *compile_version)

This works similar to SDL_Linked_Version and SDL_VERSION.
Using these you can compare the runtime version to the version that you compiled with.
These functions/macros do not require any library initialization calls before using them.

SDL_version compile_version;
const SDL_version *link_version=IMG_Linked_Version();
SDL_IMAGE_VERSION(&compile_version);
printf("compiled with SDL_image version: %d.%d.%d\n",
        compile_version.major,
        compile_version.minor,
        compile_version.patch);
printf("running with SDL_image version: %d.%d.%d\n",
        link_version->major,
        link_version->minor,
        link_version->patch);

See Also:
3.1.2 IMG_Init

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.1.2 IMG_Init

int IMG_Init(int flags)

flags
bitwise OR'd set of image formats to support by loading a library now. The values you may OR together to pass in are:
IMG_INIT_JPG
IMG_INIT_PNG
IMG_INIT_TIF

Initialize by loading support as indicated by the flags, or at least return success if support is already loaded. You may call this multiple times, which will actually require you to call IMG_Quit just once to clean up. You may call this function with a 0 to retrieve whether support was built-in or not loaded yet.
Note: to load JPG, PNG, and/or TIF images you can call IMG_Init with the right IMG_INIT_* flags OR'd together before you program gets busy, to prevent a later hiccup while it loads the library, and to check that you do have the support that you need before you try and use it.
Note: No initialization is needed nor performed when using the IMG_isJPG, IMG_isPNG, and IMG_isTIF functions.
Note: this function does not always set the error string, so do not depend on IMG_GetError being meaningful all the time.

Returns: a bitmask of all the currently initted image loaders.

// load support for the JPG and PNG image formats
int flags=IMG_INIT_JPG|IMG_INIT_PNG;
int initted=IMG_Init(flags);
if(initted&flags != flags) {
    printf("IMG_Init: Failed to init required jpg and png support!\n");
    printf("IMG_Init: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.3 IMG_Quit

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.1.3 IMG_Quit

void IMG_Quit()

This function cleans up all dynamically loaded library handles, freeing memory. If support is required again it will be initialized again, either by IMG_Init or loading an image with dynamic support required. You may call this function when IMG_Load functions are no longer needed for the JPG, PNG, and TIF image formats. You only need to call this function once, no matter how many times IMG_Init was called.

// unload the dynamically loaded image libraries
IMG_Quit();

See Also:
3.1.2 IMG_Init

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2 Loading

These functions create an SDL_Surface from image data either from a file, or SDL_RWop, or from an array of data in memory.

Automagic Loading
3.2.1 IMG_Load | Load from a file
3.2.2 IMG_Load_RW | Load using a SDL_RWop
3.2.3 IMG_LoadTyped_RW | Load more format specifically with a SDL_RWop
Specific Loaders
3.2.6 IMG_LoadBMP_RW | Load BMP using a SDL_RWop
3.2.4 IMG_LoadCUR_RW | Load CUR using a SDL_RWop
3.2.11 IMG_LoadGIF_RW | Load GIF using a SDL_RWop
3.2.5 IMG_LoadICO_RW | Load ICO using a SDL_RWop
3.2.12 IMG_LoadJPG_RW | Load JPG using a SDL_RWop
3.2.16 IMG_LoadLBM_RW | Load LBM using a SDL_RWop
3.2.10 IMG_LoadPCX_RW | Load PCX using a SDL_RWop
3.2.14 IMG_LoadPNG_RW | Load PNG using a SDL_RWop
3.2.7 IMG_LoadPNM_RW | Load PNM using a SDL_RWop
3.2.15 IMG_LoadTGA_RW | Load TGA using a SDL_RWop
3.2.13 IMG_LoadTIF_RW | Load TIF using a SDL_RWop
3.2.9 IMG_LoadXCF_RW | Load XCF using a SDL_RWop
3.2.8 IMG_LoadXPM_RW | Load XPM using a SDL_RWop
3.2.17 IMG_LoadXV_RW | Load XV using a SDL_RWop
Array Loaders
3.2.18 IMG_ReadXPMFromArray Load XPM from compiled XPM data

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.1 IMG_Load

SDL_Surface *IMG_Load(const char *file)

file
Image file name to load a surface from.

Load file for use as an image in a new surface. This actually calls IMG_LoadTyped_RW, with the file extension used as the type string. This can load all supported image files, including TGA as long as the filename ends with ".tga". It is best to call this outside of event loops, and rather keep the loaded images around until you are really done with them, as disk speed and image conversion to a surface is not that speedy. Don't forget to SDL_FreeSurface the returned surface pointer when you are through with it.
Note: If the image format loader requires initialization, it will attempt to do that the first time it is needed if you have not already called IMG_Init to load support for your image format.
Note: If the image format supports a transparent pixel, SDL_image will set the colorkey for the surface. You can enable RLE acceleration on the surface afterwards by calling:
SDL_SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, such as no support built for the image, or a file reading error.

// load sample.png into image
SDL_Surface *image;
image=IMG_Load("sample.png");
if(!image) {
    printf("IMG_Load: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.2 IMG_Load_RW, 3.2.3 IMG_LoadTyped_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.2 IMG_Load_RW

SDL_Surface *IMG_Load_RW(SDL_RWops *src, int freesrc)

src
The source SDL_RWops as a pointer. The image is loaded from this.
freesrc
A non-zero value mean is will automatically close/free the src for you.

Load src for use as a surface. This can load all supported image formats, except TGA. Using SDL_RWops is not covered here, but they enable you to load from almost any source.
Note: If the image format loader requires initialization, it will attempt to do that the first time it is needed if you have not already called IMG_Init to load support for your image format.
Note: If the image format supports a transparent pixel, SDL_image will set the colorkey for the surface. You can enable RLE acceleration on the surface afterwards by calling:
SDL_SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors.

// load sample.png in to image
SDL_Surface *image;
image=IMG_Load_RW(SDL_RWFromFile("sample.png", "rb"), 1);
if(!image) {
    printf("IMG_Load_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.1 IMG_Load, 3.2.3 IMG_LoadTyped_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.3 IMG_LoadTyped_RW

SDL_Surface *IMG_LoadTyped_RW(SDL_RWops *src, int freesrc, char *type)

src
The source SDL_RWops as a pointer. The image is loaded from this.
freesrc
A non-zero value mean is will automatically close/free the src for you.
type
A string that indicates which format type to interpret the image as.
Here is a list of the currently recognized strings (case is not important):
"BMP"
"CUR"
"GIF"
"ICO"
"JPG"
"LBM"
"PCX"
"PNG"
"PNM"
"TGA"
"TIF"
"XCF"
"XPM"
"XV"

Load src for use as a surface. This can load all supported image formats. This method does not guarantee that the format specified by type is the format of the loaded image, except in the case when TGA format is specified (or any other non-magicable format in the future). Using SDL_RWops is not covered here, but they enable you to load from almost any source.
Note: If the image format loader requires initialization, it will attempt to do that the first time it is needed if you have not already called IMG_Init to load support for your image format.
Note: If the image format supports a transparent pixel, SDL_image will set the colorkey for the surface. You can enable RLE acceleration on the surface afterwards by calling:
SDL_SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors.

// load sample.tga into image
SDL_Surface *image;
image=IMG_LoadTyped_RW(SDL_RWFromFile("sample.tga", "rb"), 1, "TGA");
if(!image) {
    printf("IMG_LoadTyped_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.1 IMG_Load, 3.2.2 IMG_Load_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.4 IMG_LoadCUR_RW

SDL_Surface *IMG_LoadCUR_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The icon image is loaded from this.

Load src as a Windows Cursor image for use as a surface, if BMP support is compiled into the SDL_image library. The CUR's mask is put into to per pixel alpha in the surface. For files with multiple images, the first one found with the highest color count is chosen.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if BMP is not supported, or a read error.

// load sample.cur into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.cur", "rb");
image=IMG_LoadCUR_RW(rwop);
if(!image) {
    printf("IMG_LoadCUR_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.1 IMG_isCUR

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.5 IMG_LoadICO_RW

SDL_Surface *IMG_LoadICO_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The icon image is loaded from this.

Load src as a Windows Icon image for use as a surface, if BMP support is compiled into the SDL_image library. The ICO's mask is put into to per pixel alpha in the surface. For files with multiple images, the first one found with the highest color count is chosen.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if BMP is not supported, or a read error.

// load sample.ico into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.ico", "rb");
image=IMG_LoadICO_RW(rwop);
if(!image) {
    printf("IMG_LoadICO_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.2 IMG_isICO

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.6 IMG_LoadBMP_RW

SDL_Surface *IMG_LoadBMP_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The BMP image is loaded from this.

Load src as a BMP image for use as a surface, if BMP support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if BMP is not supported, or a read error.

// load sample.bmp into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.bmp", "rb");
image=IMG_LoadBMP_RW(rwop);
if(!image) {
    printf("IMG_LoadBMP_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.3 IMG_isBMP

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.7 IMG_LoadPNM_RW

SDL_Surface *IMG_LoadPNM_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The PNM image is loaded from this.

Load src as a PNM image for use as a surface, if PNM support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if PNM is not supported, or a read error.

// load sample.pnm into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.pnm", "rb");
image=IMG_LoadPNM_RW(rwop);
if(!image) {
    printf("IMG_LoadPNM_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.4 IMG_isPNM

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.8 IMG_LoadXPM_RW

SDL_Surface *IMG_LoadXPM_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The XPM image is loaded from this.

Load src as a XPM image for use as a surface, if XPM support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if XPM is not supported, or a read error.

// load sample.xpm into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xpm", "rb");
image=IMG_LoadXPM_RW(rwop);
if(!image) {
    printf("IMG_LoadXPM_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.2.18 IMG_ReadXPMFromArray, 3.3.5 IMG_isXPM

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.9 IMG_LoadXCF_RW

SDL_Surface *IMG_LoadXCF_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The XCF image is loaded from this.

Load src as a XCF image for use as a surface, if XCF support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if XCF is not supported, or a read error.

// load sample.xcf into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xcf", "rb");
image=IMG_LoadXCF_RW(rwop);
if(!image) {
    printf("IMG_LoadXCF_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.6 IMG_isXCF

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.10 IMG_LoadPCX_RW

SDL_Surface *IMG_LoadPCX_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The PCX image is loaded from this.

Load src as a PCX image for use as a surface, if PCX support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if PCX is not supported, or a read error.

// load sample.pcx into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.pcx", "rb");
image=IMG_LoadPCX_RW(rwop);
if(!image) {
    printf("IMG_LoadPCX_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.7 IMG_isPCX

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.11 IMG_LoadGIF_RW

SDL_Surface *IMG_LoadGIF_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The GIF image is loaded from this.

Load src as a GIF image for use as a surface, if GIF support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if GIF is not supported, or a read error.

// load sample.gif into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.gif", "rb");
image=IMG_LoadGIF_RW(rwop);
if(!image) {
    printf("IMG_LoadGIF_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.8 IMG_isGIF

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.12 IMG_LoadJPG_RW

SDL_Surface *IMG_LoadJPG_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The JPG image is loaded from this.

Load src as a JPG image for use as a surface, if JPG support is compiled into the SDL_image library.
Note: If the image format loader requires initialization, it will attempt to do that the first time it is needed if you have not already called IMG_Init to load support for your image format.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if JPG is not supported, or a read error.

// load sample.jpg into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.jpg", "rb");
image=IMG_LoadJPG_RW(rwop);
if(!image) {
    printf("IMG_LoadJPG_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.3 IMG_LoadTyped_RW, 3.3.9 IMG_isJPG

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.13 IMG_LoadTIF_RW

SDL_Surface *IMG_LoadTIF_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The TIF image is loaded from this.

Load src as a TIF image for use as a surface, if TIF support is compiled into the SDL_image library.
Note: If the image format loader requires initialization, it will attempt to do that the first time it is needed if you have not already called IMG_Init to load support for your image format.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if TIF is not supported, or a read error.

// load sample.tif into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.tif", "rb");
image=IMG_LoadTIF_RW(rwop);
if(!image) {
    printf("IMG_LoadTIF_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.3 IMG_LoadTyped_RW, 3.3.10 IMG_isTIF

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.14 IMG_LoadPNG_RW

SDL_Surface *IMG_LoadPNG_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The PNG image is loaded from this.

Load src as a PNG image for use as a surface, if PNG support is compiled into the SDL_image library.
Note: If the image format loader requires initialization, it will attempt to do that the first time it is needed if you have not already called IMG_Init to load support for your image format.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if PNG is not supported, or a read error.

// load sample.png into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.png", "rb");
image=IMG_LoadPNG_RW(rwop);
if(!image) {
    printf("IMG_LoadPNG_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.3 IMG_LoadTyped_RW, 3.3.11 IMG_isPNG

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.15 IMG_LoadTGA_RW

SDL_Surface *IMG_LoadTGA_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The TGA image is loaded from this.

Load src as a TGA image for use as a surface, if TGA support is compiled into the SDL_image library. If you try to load a non TGA image, you might succeed even when it's not TGA image formatted data, this is because the TGA has no magic, which is a way of identifying a filetype from a signature in it's contents. So be careful with this.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if TGA is not supported, or a read error.

// load sample.tga into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.tga", "rb");
image=IMG_LoadTGA_RW(rwop);
if(!image) {
    printf("IMG_LoadTGA_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.16 IMG_LoadLBM_RW

SDL_Surface *IMG_LoadLBM_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The LBM image is loaded from this.

Load src as a LBM image for use as a surface, if LBM support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if LBM is not supported, or a read error.

// load sample.lbm into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.lbm", "rb");
image=IMG_LoadLBM_RW(rwop);
if(!image) {
    printf("IMG_LoadLBM_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.12 IMG_isLBM

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.17 IMG_LoadXV_RW

SDL_Surface *IMG_LoadXV_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The XV image is loaded from this.

Load src as a XV thumbnail image for use as a surface, if XV support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if XV is not supported, or a read error.

// load sample.xv into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xv", "rb");
image=IMG_LoadXV_RW(rwop);
if(!image) {
    printf("IMG_LoadXV_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.13 IMG_isXV

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.2.18 IMG_ReadXPMFromArray

SDL_Surface *IMG_ReadXPMFromArray(char **xpm)

xpm
The source xpm data. The XPM image is loaded from this. XPM files are C header files that define a char **variable, that variable name is what you use here.

Load xpm as a XPM image for use as a surface, if XPM support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if XPM is not supported, or a read error.

// load sample.xpm into image
#include "sample.xpm"
SDL_Surface *image;
image=IMG_ReadXPMFromArray(sample_xpm);
if(!image) {
    printf("IMG_ReadXPMFromArray: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.8 IMG_LoadXPM_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.3 Info

These functions are tests for specific file formats. They also show if the format is supported in the linked SDL_image library, assuming you have a valid image of that type.

3.3.3 IMG_isBMP | Test for valid, supportted BMP file
3.3.1 IMG_isCUR | Test for valid, supportted CUR file
3.3.8 IMG_isGIF | Test for valid, supportted GIF file
3.3.2 IMG_isICO | Test for valid, supportted ICO file
3.3.9 IMG_isJPG | Test for valid, supportted JPG file
3.3.12 IMG_isLBM | Test for valid, supportted LBM file
3.3.7 IMG_isPCX | Test for valid, supportted PCX file
3.3.11 IMG_isPNG | Test for valid, supportted PNG file
3.3.4 IMG_isPNM | Test for valid, supportted PNM file
3.3.10 IMG_isTIF | Test for valid, supportted TIF file
3.3.6 IMG_isXCF | Test for valid, supportted XCF file
3.3.5 IMG_isXPM | Test for valid, supportted XPM file
3.3.13 IMG_isXV | Test for valid, supportted XV file

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.3.1 IMG_isCUR

int IMG_isCUR(SDL_RWops *src)

src

If the BMP format is supported, then the image data is tested to see if it is readable as a CUR, otherwise it returns false (Zero).

Returns: 1 if the image is a CUR and the BMP format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.cur to see if it is a CUR
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.cur", "rb");
if(IMG_isCUR(rwop))
    printf("sample.cur is a CUR file.\n");
else
    printf("sample.cur is not a CUR file, or BMP support is not available.\n");

See Also:
3.2.4 IMG_LoadCUR_RW, 3.2.3 IMG_LoadTyped_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.3.2 IMG_isICO

int IMG_isICO(SDL_RWops *src)

src

If the BMP format is supported, then the image data is tested to see if it is readable as an ICO, otherwise it returns false (Zero).

Returns: 1 if the image is an ICO and the BMP format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.ico to see if it is an ICO
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.ico", "rb");
if(IMG_isICO(rwop))
    printf("sample.ico is an ICO file.\n");
else
    printf("sample.ico is not an ICO file, or BMP support is not available.\n");

See Also:
3.2.5 IMG_LoadICO_RW, 3.2.3 IMG_LoadTyped_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.3.3 IMG_isBMP

int IMG_isBMP(SDL_RWops *src)

src

If the BMP format is supported, then the image data is tested to see if it is readable as a BMP, otherwise it returns false (Zero).

Returns: 1 if the image is a BMP and the BMP format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.bmp to see if it is a BMP
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.bmp", "rb");
if(IMG_isBMP(rwop))
    printf("sample.bmp is a BMP file.\n");
else
    printf("sample.bmp is not a BMP file, or BMP support is not available.\n");

See Also:
3.2.6 IMG_LoadBMP_RW, 3.2.3 IMG_LoadTyped_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.3.4 IMG_isPNM

int IMG_isPNM(SDL_RWops *src)

src

If the PNM format is supported, then the image data is tested to see if it is readable as a PNM, otherwise it returns false (Zero).

Returns: 1 if the image is a PNM and the PNM format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.pnm to see if it is a PNM
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.pnm", "rb");
if(IMG_isPNM(rwop))
    printf("sample.pnm is a PNM file.\n");
else
    printf("sample.pnm is not a PNM file, or PNM support is not available.\n");

See Also:
3.2.7 IMG_LoadPNM_RW, 3.2.3 IMG_LoadTyped_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.3.5 IMG_isXPM

int IMG_isXPM(SDL_RWops *src)

src

If the XPM format is supported, then the image data is tested to see if it is readable as a XPM, otherwise it returns false (Zero).

Returns: 1 if the image is a XPM and the XPM format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.xpm to see if it is a XPM
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xpm", "rb");
if(IMG_isXPM(rwop))
    printf("sample.xpm is a XPM file.\n");
else
    printf("sample.xpm is not a XPM file, or XPM support is not available.\n");

See Also:
3.2.8 IMG_LoadXPM_RW, 3.2.3 IMG_LoadTyped_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.3.6 IMG_isXCF

int IMG_isXCF(SDL_RWops *src)

src

If the XCF format is supported, then the image data is tested to see if it is readable as a XCF, otherwise it returns false (Zero).

Returns: 1 if the image is a XCF and the XCF format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.xcf to see if it is a XCF
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xcf", "rb");
if(IMG_isXCF(rwop))
    printf("sample.xcf is a XCF file.\n");
else
    printf("sample.xcf is not a XCF file, or XCF support is not available.\n");

See Also:
3.2.9 IMG_LoadXCF_RW, 3.2.3 IMG_LoadTyped_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.3.7 IMG_isPCX

int IMG_isPCX(SDL_RWops *src)

src

If the PCX format is supported, then the image data is tested to see if it is readable as a PCX, otherwise it returns false (Zero).

Returns: 1 if the image is a PCX and the PCX format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.pcx to see if it is a PCX
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.pcx", "rb");
if(IMG_isPCX(rwop))
    printf("sample.pcx is a PCX file.\n");
else
    printf("sample.pcx is not a PCX file, or PCX support is not available.\n");

See Also:
3.2.10 IMG_LoadPCX_RW, 3.2.3 IMG_LoadTyped_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.3.8 IMG_isGIF

int IMG_isGIF(SDL_RWops *src)

src

If the GIF format is supported, then the image data is tested to see if it is readable as a GIF, otherwise it returns false (Zero).

Returns: 1 if the image is a GIF and the GIF format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.gif to see if it is a GIF
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.gif", "rb");
if(IMG_isGIF(rwop))
    printf("sample.gif is a GIF file.\n");
else
    printf("sample.gif is not a GIF file, or GIF support is not available.\n");

See Also:
3.2.11 IMG_LoadGIF_RW, 3.2.3 IMG_LoadTyped_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.3.9 IMG_isJPG

int IMG_isJPG(SDL_RWops *src)

src

If the JPG format is supported, then the image data is tested to see if it is readable as a JPG, otherwise it returns false (Zero).

Returns: 1 if the image is a JPG and the JPG format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.jpg to see if it is a JPG
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.jpg", "rb");
if(IMG_isJPG(rwop))
    printf("sample.jpg is a JPG file.\n");
else
    printf("sample.jpg is not a JPG file, or JPG support is not available.\n");

See Also:
3.2.12 IMG_LoadJPG_RW, 3.2.3 IMG_LoadTyped_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.3.10 IMG_isTIF

int IMG_isTIF(SDL_RWops *src)

src

If the TIF format is supported, then the image data is tested to see if it is readable as a TIF, otherwise it returns false (Zero).

Returns: 1 if the image is a TIF and the TIF format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.tif to see if it is a TIF
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.tif", "rb");
if(IMG_isTIF(rwop))
    printf("sample.tif is a TIF file.\n");
else
    printf("sample.tif is not a TIF file, or TIF support is not available.\n");

See Also:
3.2.13 IMG_LoadTIF_RW, 3.2.3 IMG_LoadTyped_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.3.11 IMG_isPNG

int IMG_isPNG(SDL_RWops *src)

src

If the PNG format is supported, then the image data is tested to see if it is readable as a PNG, otherwise it returns false (Zero).

Returns: 1 if the image is a PNG and the PNG format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.png to see if it is a PNG
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.png", "rb");
if(IMG_isPNG(rwop))
    printf("sample.png is a PNG file.\n");
else
    printf("sample.png is not a PNG file, or PNG support is not available.\n");

See Also:
3.2.14 IMG_LoadPNG_RW, 3.2.3 IMG_LoadTyped_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.3.12 IMG_isLBM

int IMG_isLBM(SDL_RWops *src)

src

If the LBM format is supported, then the image data is tested to see if it is readable as a LBM, otherwise it returns false (Zero).

Returns: 1 if the image is a LBM and the LBM format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.lbm to see if it is a LBM
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.lbm", "rb");
if(IMG_isLBM(rwop))
    printf("sample.lbm is a LBM file.\n");
else
    printf("sample.lbm is not a LBM file, or LBM support is not available.\n");

See Also:
3.2.16 IMG_LoadLBM_RW, 3.2.3 IMG_LoadTyped_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.3.13 IMG_isXV

int IMG_isXV(SDL_RWops *src)

src

If the XV format is supported, then the image data is tested to see if it is readable as an XV thumbnail, otherwise it returns false (Zero).

Returns: 1 if the image is an XV thumbnail and the XV format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.xv to see if it is an XV thumbnail
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xv", "rb");
if(IMG_isXV(rwop))
    printf("sample.xv is an XV file.\n");
else
    printf("sample.xv is not an XV file, or XV support is not available.\n");

See Also:
3.2.17 IMG_LoadXV_RW, 3.2.3 IMG_LoadTyped_RW

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.4 Errors

These functions are used for error status strings that should help the user and developer understand why a function failed.

3.4.1 IMG_SetError | Set the current error string
3.4.2 IMG_GetError | Get the current error string

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.4.1 IMG_SetError

void IMG_SetError(const char *fmt, ...)

This is the same as SDL_SetError, which sets the error string which may be fetched with IMG_GetError (or SDL_GetError). This functions acts like printf, except that it is limited to SDL_ERRBUFIZE(1024) chars in length. It only accepts the following format types: %s, %d, %f, %p. No variations are supported, like %.2f would not work. For any more specifics read the SDL docs.

int myimagefunc(int i) {
    IMG_SetError("myimagefunc is not implemented! %d was passed in.",i);
    return(-1);
}

See Also:
3.4.2 IMG_GetError

[ < ] [ > ] [ << ] [ Up ] [ >> ]

3.4.2 IMG_GetError

char *IMG_GetError()

This is the same as SDL_GetError, which returns the last error set as a string which you may use to tell the user what happened when an error status has been returned from an SDL_image function call.

Returns: a char pointer (string) containing a humam readble version or the reason for the last error that occured.

printf("Oh My Goodness, an error : %s", IMG_GetError());

See Also:
3.4.1 IMG_SetError

[ < ] [ > ] [ << ] [ Up ] [ >> ]

4. Defines

IMG_MAJOR_VERSION
1
SDL_image library major number at compilation time
IMG_MINOR_VERSION
2
SDL_image library minor number at compilation time
IMG_PATCHLEVEL
8
SDL_image library patch level at compilation time
IMG_INIT_JPG
1
IMG_Init JPG image format support flag
IMG_INIT_PNG
2
IMG_Init PNG image format support flag
IMG_INIT_TIF
4
IMG_Init TIF image format support flag

[ < ] [ > ] [ << ] [ Up ] [ >> ]

Index

Jump to: I R S

 | Index Entry | Section
I |  |
 | IMG_GetError | 3.4.2 IMG_GetError
 | IMG_Init | 3.1.2 IMG_Init
 | IMG_INIT_JPG | 4. Defines
 | IMG_INIT_PNG | 4. Defines
 | IMG_INIT_TIF | 4. Defines
 | IMG_isBMP | 3.3.3 IMG_isBMP
 | IMG_isCUR | 3.3.1 IMG_isCUR
 | IMG_isGIF | 3.3.8 IMG_isGIF
 | IMG_isICO | 3.3.2 IMG_isICO
 | IMG_isJPG | 3.3.9 IMG_isJPG
 | IMG_isLBM | 3.3.12 IMG_isLBM
 | IMG_isPCX | 3.3.7 IMG_isPCX
 | IMG_isPNG | 3.3.11 IMG_isPNG
 | IMG_isPNM | 3.3.4 IMG_isPNM
 | IMG_isTIF | 3.3.10 IMG_isTIF
 | IMG_isXCF | 3.3.6 IMG_isXCF
 | IMG_isXPM | 3.3.5 IMG_isXPM
 | IMG_isXV | 3.3.13 IMG_isXV
 | IMG_Linked_Version | 3.1.1 IMG_Linked_Version
 | IMG_Load | 3.2.1 IMG_Load
 | IMG_Load_RW | 3.2.2 IMG_Load_RW
 | IMG_LoadBMP_RW | 3.2.6 IMG_LoadBMP_RW
 | IMG_LoadCUR_RW | 3.2.4 IMG_LoadCUR_RW
 | IMG_LoadGIF_RW | 3.2.11 IMG_LoadGIF_RW
 | IMG_LoadICO_RW | 3.2.5 IMG_LoadICO_RW
 | IMG_LoadJPG_RW | 3.2.12 IMG_LoadJPG_RW
 | IMG_LoadLBM_RW | 3.2.16 IMG_LoadLBM_RW
 | IMG_LoadPCX_RW | 3.2.10 IMG_LoadPCX_RW
 | IMG_LoadPNG_RW | 3.2.14 IMG_LoadPNG_RW
 | IMG_LoadPNM_RW | 3.2.7 IMG_LoadPNM_RW
 | IMG_LoadTGA_RW | 3.2.15 IMG_LoadTGA_RW
 | IMG_LoadTIF_RW | 3.2.13 IMG_LoadTIF_RW
 | IMG_LoadTyped_RW | 3.2.3 IMG_LoadTyped_RW
 | IMG_LoadXCF_RW | 3.2.9 IMG_LoadXCF_RW
 | IMG_LoadXPM_RW | 3.2.8 IMG_LoadXPM_RW
 | IMG_LoadXV_RW | 3.2.17 IMG_LoadXV_RW
 | IMG_MAJOR_VERSION | 4. Defines
 | IMG_MINOR_VERSION | 4. Defines
 | IMG_PATCHLEVEL | 4. Defines
 | IMG_Quit | 3.1.3 IMG_Quit
 | IMG_ReadXPMFromArray | 3.2.18 IMG_ReadXPMFromArray
 | IMG_SetError | 3.4.1 IMG_SetError
R |  |
 | README | 1. Overview
S |  |
 | sdl-config | 2.2 Compiling
 | SDL_IMAGE_VERSION | 3.1.1 IMG_Linked_Version
 | SDL_Surface | 3.2 Loading

Jump to: I R S

Table of Contents

    1. Overview
    2. Getting Started
      2.1 Includes
      2.2 Compiling
    3. Functions
      3.1 General
        3.1.1 IMG_Linked_Version
        3.1.2 IMG_Init
        3.1.3 IMG_Quit
      3.2 Loading
        3.2.1 IMG_Load
        3.2.2 IMG_Load_RW
        3.2.3 IMG_LoadTyped_RW
        3.2.4 IMG_LoadCUR_RW
        3.2.5 IMG_LoadICO_RW
        3.2.6 IMG_LoadBMP_RW
        3.2.7 IMG_LoadPNM_RW
        3.2.8 IMG_LoadXPM_RW
        3.2.9 IMG_LoadXCF_RW
        3.2.10 IMG_LoadPCX_RW
        3.2.11 IMG_LoadGIF_RW
        3.2.12 IMG_LoadJPG_RW
        3.2.13 IMG_LoadTIF_RW
        3.2.14 IMG_LoadPNG_RW
        3.2.15 IMG_LoadTGA_RW
        3.2.16 IMG_LoadLBM_RW
        3.2.17 IMG_LoadXV_RW
        3.2.18 IMG_ReadXPMFromArray
      3.3 Info
        3.3.1 IMG_isCUR
        3.3.2 IMG_isICO
        3.3.3 IMG_isBMP
        3.3.4 IMG_isPNM
        3.3.5 IMG_isXPM
        3.3.6 IMG_isXCF
        3.3.7 IMG_isPCX
        3.3.8 IMG_isGIF
        3.3.9 IMG_isJPG
        3.3.10 IMG_isTIF
        3.3.11 IMG_isPNG
        3.3.12 IMG_isLBM
        3.3.13 IMG_isXV
      3.4 Errors
        3.4.1 IMG_SetError
        3.4.2 IMG_GetError
    4. Defines
    Index

Short Table of Contents

1. Overview
2. Getting Started
3. Functions
4. Defines
Index

About this document

This document was generated on November, 3 2009 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated on November, 3 2009 using texi2html


SDL_mixer 1.2.10

1. Overview The README from the SDL_mixer distribution

2. Getting Started Using SDL_mixer

3. Conflicts Conflicts with SDL Audio functions

4. Functions | Functions supported by the SDL_mixer API
5. Types | Types used with the SDL_mixer API
6. Defines | Defined values/macros in the SDL_mixer API

7. Glossary Terms used in this document

Index Index of selected words
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1. Overview

A Little Bit About Me

I am currently, as I write this document, a programmer for Raytheon. There I do all sorts of communications, network, GUI, and other general programming tasks in C/C++ on the Solaris and sometimes Linux Operating Systems. I have been programming sound code in my free time for only a little while now. Sound is an integral part to any game. The human senses are mostly starved during video game play. there's only some tactile feedback on some controlers, and of course the eyes are in use but only for about 30% of their viewing area. So to add more we do need sound to help the game player feel more in the action, and to set certain moods as the game progresses. Sound ends up accounting for perhaps 50% or more of a gamers experience. Music and sound effects are all integral parts of the gaming experience. While this document doesn't explain how to get music and samples to use, it will explain how to use them with SDL_mixer.

Feel free to contact me: JonathanCAtkins@gmail.com

I am also usually on IRC at irc.freenode.net in the #SDL channel as LIM

This is the README in the SDL_mixer source archive.

SDL_mixer 1.2

The latest version of this library is available from:
SDL_mixer Homepage

Due to popular demand, here is a simple multi-channel audio mixer. It supports 8 channels of 16 bit stereo audio, plus a single channel of music, mixed by the popular MikMod MOD, Timidity MIDI and SMPEG MP3 libraries.

See the header file SDL_mixer.h and the examples playwave.c and playmus.c for documentation on this mixer library.

The mixer can currently load Microsoft WAVE files and Creative Labs VOC files as audio samples, and can load MIDI files via Timidity and the following music formats via MikMod: .MOD .S3M .IT .XM. It can load Ogg Vorbis streams as music if built with the Ogg Vorbis libraries, and finally it can load MP3 music using the SMPEG library.

The process of mixing MIDI files to wave output is very CPU intensive, so if playing regular WAVE files sound great, but playing MIDI files sound choppy, try using 8-bit audio, mono audio, or lower frequencies.

To play MIDI files, you'll need to get a complete set of GUS patches from: Timidity GUS Patches and unpack them in /usr/local/lib under UNIX, and C:\ under Win32.

This library is available under the GNU Library General Public License, see the file "COPYING" for details.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2. Getting Started

This assumes you have gotten SDL_mixer and installed it on your system. SDL_mixer has an INSTALL document in the source distribution to help you get it compiled and installed.

Generally, installation consists of:

./configure
make
make install

SDL_mixer supports playing music and sound samples from the following formats:
- WAVE/RIFF (.wav)
- AIFF (.aiff)
- VOC (.voc)
- MOD (.mod .xm .s3m .669 .it .med and more) requiring libmikmod on system
- MIDI (.mid) using timidity or native midi hardware
- OggVorbis (.ogg) requiring ogg/vorbis libraries on system
- MP3 (.mp3) requiring SMPEG or MAD library on system
- FLAC (.flac) requiring the FLAC library on system - also any command-line player, which is not mixed by SDL_mixer...

You may also want to look at some demonstration code which may be downloaded from:
http://www.jonatkins.org/SDL_mixer/

2.1 Includes | The include files to use for SDL_mixer
2.2 Compiling | Using the SDL_mixer library and header file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.1 Includes

To use SDL_mixer functions in a C/C++ source code file, you must use the SDL_mixer.h include file:

#include "SDL_mixer.h"

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2 Compiling

To link with SDL_mixer you should use sdl-config to get the required SDL compilation options. After that, compiling with SDL_mixer is quite easy.
Note: Some systems may not have the SDL_mixer library and include file in the same place as the SDL library and includes are located, in that case you will need to add more -I and -L paths to these command lines.

Simple Example for compiling an object file:

cc -c `sdl-config --cflags` mysource.c

Simple Example for compiling an object file:

cc -o myprogram mysource.o `sdl-config --libs` -lSDL_mixer

Now myprogram is ready to run.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3. Conflicts

When using SDL_mixer functions you need to avoid the following functions from SDL:

SDL_OpenAudio
Use Mix_OpenAudio instead.
SDL_CloseAudio
Use Mix_CloseAudio instead.
SDL_PauseAudio
Use Mix_Pause(-1) and Mix_PauseMusic instead, to pause.
Use Mix_Resume(-1) and Mix_ResumeMusic instead, to unpause.
SDL_LockAudio
This is just not needed since SDL_mixer handles this for you.
Using it may cause problems as well.
SDL_UnlockAudio
This is just not needed since SDL_mixer handles this for you.
Using it may cause problems as well.

You may call the following functions freely:

SDL_AudioDriverName
This will still work as usual.
SDL_GetAudioStatus
This will still work, though it will likely return SDL_AUDIO_PLAYING even though SDL_mixer is just playing silence.

It is also a BAD idea to call SDL_mixer and SDL audio functions from a callback. Callbacks include Effects functions and other SDL_mixer audio hooks.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4. Functions

These are the functions in the SDL_mixer API.

4.1 General | API activation
4.2 Samples | Loading sounds from files or memory
4.3 Channels | Sound effect channels
4.4 Groups | Sound effect channel grouping
4.5 Music | Music playing
4.6 Effects | Special effects processing

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1 General

These functions are useful, as they are the only/best ways to work with SDL_mixer.

Info
4.1.1 Mix_Linked_Version Get version number
Activation
4.1.2 Mix_Init | Initialize SDL_mixer
4.1.3 Mix_Quit | Cleanup SDL_mixer
4.1.4 Mix_OpenAudio | Open sound mixer
4.1.5 Mix_CloseAudio | Close sound mixer
Errors
4.1.6 Mix_SetError | Set the current error string
4.1.7 Mix_GetError | Get the current error string
Settings
4.1.8 Mix_QuerySpec Get output format

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1.1 Mix_Linked_Version

const SDL_version *Mix_Linked_Version()
void SDL_MIXER_VERSION(SDL_version *compile_version)

This works similar to SDL_Linked_Version and SDL_VERSION.
Using these you can compare the runtime version to the version that you compiled with.

SDL_version compile_version;
const SDL_version *link_version=Mix_Linked_Version();
SDL_MIXER_VERSION(&compile_version);
printf("compiled with SDL_mixer version: %d.%d.%d\n",
        compile_version.major,
        compile_version.minor,
        compile_version.patch);
printf("running with SDL_mixer version: %d.%d.%d\n",
        link_version->major,
        link_version->minor,
        link_version->patch);

See Also:
4.1.4 Mix_OpenAudio, 4.1.8 Mix_QuerySpec

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1.2 Mix_Init

int Mix_Init(int flags)

flags
bitwise OR'd set of sample/music formats to support by loading a library now. The values you may OR together to pass in are:
MIX_INIT_FLAC
MIX_INIT_MOD
MIX_INIT_MP3
MIX_INIT_OGG

Initialize by loading support as indicated by the flags, or at least return success if support is already loaded. You may call this multiple times, which will actually require you to call Mix_Quit just once to clean up. You may call this function with a 0 to retrieve whether support was built-in or not loaded yet.
Note: you can call Mix_Init with the right MIX_INIT_* flags OR'd together before you program gets busy, to prevent a later hiccup while it loads and unloads the library, and to check that you do have the support that you need before you try and use it.
Note: this function does not always set the error string, so do not depend on Mix_GetError being meaningful all the time.

Returns: a bitmask of all the currently initted sample/music loaders.

// load support for the OGG and MOD sample/music formats
int flags=MIX_INIT_OGG|MIX_INIT_MOD;
int initted=Mix_Init(flags);
if(initted&flags != flags) {
    printf("Mix_Init: Failed to init required ogg and mod support!\n");
    printf("Mix_Init: %s\n", Mix_GetError());
    // handle error
}

See Also:
4.1.3 Mix_Quit

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1.3 Mix_Quit

void Mix_Quit()

This function cleans up all dynamically loaded library handles, freeing memory. If support is required again it will be initialized again, either by Mix_Init or loading a sample or some music with dynamic support required. You may call this function when Mix_Load functions are no longer needed for the MIX_INIT_* formats. You should call this function for each time Mix_Init was called, otherwise it may not free all the dynamic library resources until the program ends. This is done so that multiple unrelated modules of a program may call Mix_Init and Mix_Quit without affecting the others performance and needs.

// indicate that we are ready to unload the dynamically loaded libraries
Mix_Quit();

NOTE: Since each call to Mix_Init may set different flags, there is no way, currently, to request how many times each one was initted. In other words, the only way to quit for sure is to do a loop like so:
// force a quit
while(Mix_Init(0))
    Mix_Quit();

See Also:
4.1.2 Mix_Init

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1.4 Mix_OpenAudio

int Mix_OpenAudio(int frequency, Uint16 format, int channels, int chunksize)

frequency
Output sampling frequency in samples per second (Hz).
you might use MIX_DEFAULT_FREQUENCY(22050) since that is a good value for most games.
format
Output sample format.
channels
Number of sound channels in output.
Set to 2 for stereo, 1 for mono. This has nothing to do with mixing channels.
chunksize
Bytes used per output sample.

Initialize the mixer API.
This must be called before using other functions in this library.
SDL must be initialized with SDL_INIT_AUDIO before this call. frequency would be 44100 for 44.1KHz, which is CD audio rate. Most games use 22050, because 44100 requires too much CPU power on older computers. chunksize is the size of each mixed sample. The smaller this is the more your hooks will be called. If make this too small on a slow system, sound may skip. If made to large, sound effects will lag behind the action more. You want a happy medium for your target computer. You also may make this 4096, or larger, if you are just playing music. MIX_CHANNELS(8) mixing channels will be allocated by default. You may call this function multiple times, however you will have to call Mix_CloseAudio just as many times for the device to actually close. The format will not changed on subsequent calls until fully closed. So you will have to close all the way before trying to open with different format parameters.

format is based on SDL audio support, see SDL_audio.h. Here are the values listed there:

AUDIO_U8
Unsigned 8-bit samples
AUDIO_S8
Signed 8-bit samples
AUDIO_U16LSB
Unsigned 16-bit samples, in little-endian byte order
AUDIO_S16LSB
Signed 16-bit samples, in little-endian byte order
AUDIO_U16MSB
Unsigned 16-bit samples, in big-endian byte order
AUDIO_S16MSB
Signed 16-bit samples, in big-endian byte order
AUDIO_U16
same as AUDIO_U16LSB (for backwards compatability probably)
AUDIO_S16
same as AUDIO_S16LSB (for backwards compatability probably)
AUDIO_U16SYS
Unsigned 16-bit samples, in system byte order
AUDIO_S16SYS
Signed 16-bit samples, in system byte order

MIX_DEFAULT_FORMAT is the same as AUDIO_S16SYS.

Returns: 0 on success, -1 on errors

// start SDL with audio support
if(SDL_Init(SDL_INIT_AUDIO)==-1) {
    printf("SDL_Init: %s\n", SDL_GetError());
    exit(1);
}
// open 44.1KHz, signed 16bit, system byte order,
//      stereo audio, using 1024 byte chunks
if(Mix_OpenAudio(44100, MIX_DEFAULT_FORMAT, 2, 1024)==-1) {
    printf("Mix_OpenAudio: %s\n", Mix_GetError());
    exit(2);
}

See Also:
4.1.5 Mix_CloseAudio, 4.1.8 Mix_QuerySpec, 4.3.1 Mix_AllocateChannels

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1.5 Mix_CloseAudio

void Mix_CloseAudio()

Shutdown and cleanup the mixer API.
After calling this all audio is stopped, the device is closed, and the SDL_mixer functions should not be used. You may, of course, use Mix_OpenAudio to start the functionality again.
Note: This function doesn't do anything until you have called it the same number of times that you called Mix_OpenAudio. You may use Mix_QuerySpec to find out how many times Mix_CloseAudio needs to be called before the device is actually closed.

Mix_CloseAudio();
// you could SDL_Quit(); here...or not.

See Also:
4.1.4 Mix_OpenAudio, 4.1.8 Mix_QuerySpec

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1.6 Mix_SetError

void Mix_SetError(const char *fmt, ...)

This is the same as SDL_SetError, which sets the error string which may be fetched with Mix_GetError (or SDL_GetError). This functions acts like printf, except that it is limited to SDL_ERRBUFIZE(1024) chars in length. It only accepts the following format types: %s, %d, %f, %p. No variations are supported, like %.2f would not work. For any more specifics read the SDL docs.

int mymixfunc(int i) {
    Mix_SetError("mymixfunc is not implemented! %d was passed in.",i);
    return(-1);
}

See Also:
4.1.7 Mix_GetError

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1.7 Mix_GetError

char *Mix_GetError()

This is the same as SDL_GetError, which returns the last error set as a string which you may use to tell the user what happened when an error status has been returned from an SDL_mixer function call.

Returns: a char pointer (string) containing a humam readble version or the reason for the last error that occured.

printf("Oh My Goodness, an error : %s", Mix_GetError());

See Also:
4.1.6 Mix_SetError

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1.8 Mix_QuerySpec

int Mix_QuerySpec(int *frequency, Uint16 *format, int *channels)

frequency
A pointer to an int where the frequency actually used by the opened audio device will be stored.
format
A pointer to a Uint16 where the output format actually being used by the audio device will be stored.
channels
A pointer to an int where the number of audio channels will be stored.
2 will mean stereo, 1 will mean mono.

Get the actual audio format in use by the opened audio device. This may or may not match the parameters you passed to Mix_OpenAudio.

Returns: 0 on error. If the device was open the number of times it was opened will be returned. The values of the arguments variables are not set on an error.

// get and print the audio format in use
int numtimesopened, frequency, channels;
Uint16 format;
numtimesopened=Mix_QuerySpec(&frequency, &format, &channels);
if(!numtimesopened) {
    printf("Mix_QuerySpec: %s\n",Mix_GetError());
}
else {
    char *format_str="Unknown";
    switch(format) {
        case AUDIO_U8: format_str="U8"; break;
        case AUDIO_S8: format_str="S8"; break;
        case AUDIO_U16LSB: format_str="U16LSB"; break;
        case AUDIO_S16LSB: format_str="S16LSB"; break;
        case AUDIO_U16MSB: format_str="U16MSB"; break;
        case AUDIO_S16MSB: format_str="S16MSB"; break;
    }
    printf("opened=%d times  frequency=%dHz  format=%s  channels=%d",
            numtimesopened, frequency, format_str, channels);
}

See Also:
4.1.4 Mix_OpenAudio

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.2 Samples

These functions work with Mix_Chunk samples.

Loading
4.2.1 Mix_GetNumChunkDecoders | Number of sample format types that can be decoded
4.2.2 Mix_GetChunkDecoder | Name of enumerated sample format type decoder
4.2.3 Mix_LoadWAV | From a file
4.2.4 Mix_LoadWAV_RW | Using RWops
4.2.5 Mix_QuickLoad_WAV | From memory, in output format already
4.2.6 Mix_QuickLoad_RAW | From memory, in output format already
Settings
4.2.7 Mix_VolumeChunk Set mix volume
Freeing
4.2.8 Mix_FreeChunk Free sample

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.2.1 Mix_GetNumChunkDecoders

int Mix_GetNumChunkDecoders()

Get the number of sample chunk decoders available from the Mix_GetChunkDecoder function. This number can be different for each run of a program, due to the change in availability of shared libraries that support each format.

Returns: The number of sample chunk decoders available.

// print the number of sample chunk decoders available
printf("There are %d sample chunk deocoders available\n", Mix_GetNumChunkDecoders());

See Also:
4.5.1 Mix_GetNumMusicDecoders, 4.2.2 Mix_GetChunkDecoder, 4.2.3 Mix_LoadWAV

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.2.2 Mix_GetChunkDecoder

const char *Mix_GetChunkDecoder(int index)

index
The index number of sample chunk decoder to get.
In the range from 0(zero) to Mix_GetNumChunkDecoders()-1, inclusive.

Get the name of the indexed sample chunk decoder. You need to get the number of sample chunk decoders available using the Mix_GetNumChunkDecoders function.

Returns: The name of the indexed sample chunk decoder. This string is owned by the SDL_mixer library, do not modify or free it. It is valid until you call Mix_CloseAudio the final time.

// print sample chunk decoders available
int i,max=Mix_GetNumChunkDecoders();
for(i=0; i<max; ++i)
    printf("Sample chunk decoder %d is for %s",Mix_GetChunkDecoder(i));

See Also:
4.2.1 Mix_GetNumChunkDecoders, 4.5.2 Mix_GetMusicDecoder, 4.2.3 Mix_LoadWAV

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.2.3 Mix_LoadWAV

Mix_Chunk *Mix_LoadWAV(char *file)

file
File name to load sample from.

Load file for use as a sample. This is actually Mix_LoadWAV_RW(SDL_RWFromFile(file, "rb"), 1). This can load WAVE, AIFF, RIFF, OGG, and VOC files.
Note: You must call SDL_OpenAudio before this. It must know the output characteristics so it can convert the sample for playback, it does this conversion at load time.

Returns: a pointer to the sample as a Mix_Chunk. NULL is returned on errors.

// load sample.wav in to sample
Mix_Chunk *sample;
sample=Mix_LoadWAV("sample.wav");
if(!sample) {
    printf("Mix_LoadWAV: %s\n", Mix_GetError());
    // handle error
}

See Also:
4.2.4 Mix_LoadWAV_RW, 4.2.5 Mix_QuickLoad_WAV, 4.2.8 Mix_FreeChunk

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.2.4 Mix_LoadWAV_RW

Mix_Chunk *Mix_LoadWAV_RW(SDL_RWops *src, int freesrc)

src
The source SDL_RWops as a pointer. The sample is loaded from this.
freesrc
A non-zero value mean is will automatically close/free the src for you.

Load src for use as a sample. This can load WAVE, AIFF, RIFF, OGG, and VOC formats. Using SDL_RWops is not covered here, but they enable you to load from almost any source. Note: You must call SDL_OpenAudio before this. It must know the output characteristics so it can convert the sample for playback, it does this conversion at load time.

Returns: a pointer to the sample as a Mix_Chunk. NULL is returned on errors.

// load sample.wav in to sample
Mix_Chunk *sample;
sample=Mix_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1);
if(!sample) {
    printf("Mix_LoadWAV_RW: %s\n", Mix_GetError());
    // handle error
}

See Also:
4.2.3 Mix_LoadWAV, 4.2.5 Mix_QuickLoad_WAV, 4.2.8 Mix_FreeChunk

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.2.5 Mix_QuickLoad_WAV

Mix_Chunk *Mix_QuickLoad_WAV(Uint8 *mem)

mem
Memory buffer containing a WAVE file in output format.

Load mem as a WAVE/RIFF file into a new sample. The WAVE in mem must be already in the output format. It would be better to use Mix_LoadWAV_RW if you aren't sure.
Note: This function does very little checking. If the format mismatches the output format, or if the buffer is not a WAVE, it will not return an error. This is probably a dangerous function to use.

Returns: a pointer to the sample as a Mix_Chunk. NULL is returned on errors.

// quick-load a wave from memory
// Uint8 *wave; // I assume you have the wave loaded raw,
                // or compiled in the program...
Mix_Chunk *wave_chunk;
if(!(wave_chunk=Mix_QuickLoad_WAV(wave))) {
    printf("Mix_QuickLoad_WAV: %s\n", Mix_GetError());
    // handle error
}

See Also:
4.2.3 Mix_LoadWAV, 4.2.6 Mix_QuickLoad_RAW, 4.2.8 Mix_FreeChunk

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.2.6 Mix_QuickLoad_RAW

Mix_Chunk *Mix_QuickLoad_RAW(Uint8 *mem)

mem
Memory buffer containing a WAVE file in output format.

Load mem as a raw sample. The data in mem must be already in the output format. If you aren't sure what you are doing, this is not a good function for you!
Note: This function does very little checking. If the format mismatches the output format it will not return an error. This is probably a dangerous function to use.

Returns: a pointer to the sample as a Mix_Chunk. NULL is returned on errors, such as when out of memory.

// quick-load a raw sample from memory
// Uint8 *raw; // I assume you have the raw data here,
                // or compiled in the program...
Mix_Chunk *raw_chunk;
if(!(raw_chunk=Mix_QuickLoad_RAW(raw))) {
    printf("Mix_QuickLoad_RAW: %s\n", Mix_GetError());
    // handle error
}

See Also:
4.2.3 Mix_LoadWAV, 4.2.5 Mix_QuickLoad_WAV, 4.2.8 Mix_FreeChunk

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.2.7 Mix_VolumeChunk

int Mix_VolumeChunk(Mix_Chunk *chunk, int volume)

chunk
Pointer to the Mix_Chunk to set the volume in.
volume
The volume to use from 0 to MIX_MAX_VOLUME(128).
If greater than MIX_MAX_VOLUME,
then it will be set to MIX_MAX_VOLUME.
If less than 0 then chunk->volume will not be set.

Set chunk->volume to volume.
The volume setting will take effect when the chunk is used on a channel, being mixed into the output.

Returns: previous chunk->volume setting. if you passed a negative value for volume then this volume is still the current volume for the chunk.

// set the sample's volume to 1/2
// Mix_Chunk *sample;
int previous_volume;
previous_volume=Mix_VolumeChunk(sample, MIX_MAX_VOLUME/2);
printf("previous_volume: %d\n", previous_volume);

See Also:
5.1 Mix_Chunk

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.2.8 Mix_FreeChunk

void Mix_FreeChunk(Mix_Chunk *chunk)

chunk
Pointer to the Mix_Chunk to free.

Free the memory used in chunk, and free chunk itself as well. Do not use chunk after this without loading a new sample to it. Note: It's a bad idea to free a chunk that is still being played...

// free the sample
// Mix_Chunk *sample;
Mix_FreeChunk(sample);
sample=NULL; // to be safe...

See Also:
4.2.3 Mix_LoadWAV, 4.2.4 Mix_LoadWAV_RW, 4.2.5 Mix_QuickLoad_WAV,

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3 Channels

These functions work with sound effect mixer channels. Music is not affected by these functions.

Setup
4.3.1 Mix_AllocateChannels | Set the number of channels to mix
4.3.2 Mix_Volume | Set the mix volume of a channel
Playing
4.3.3 Mix_PlayChannel | Play loop
4.3.4 Mix_PlayChannelTimed | Play loop and limit by time
4.3.5 Mix_FadeInChannel | Play loop with fade in
4.3.6 Mix_FadeInChannelTimed | Play loop with fade in and limit by time
Pausing
4.3.7 Mix_Pause | Pause a channel
4.3.8 Mix_Resume | Resume a paused channel
Stopping
4.3.9 Mix_HaltChannel | Stop playing on a channel
4.3.10 Mix_ExpireChannel | Change the timed stoppage of a channel
4.3.11 Mix_FadeOutChannel | Stop playing channel after timed fade out
4.3.12 Mix_ChannelFinished | Set callback for when channel finishes playing
Info
4.3.13 Mix_Playing | Get the active playing status of a channel
4.3.14 Mix_Paused | Get the pause status of a channel
4.3.15 Mix_FadingChannel | Get the fade status of a channel
4.3.16 Mix_GetChunk | Get the sample playing on a channel

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3.1 Mix_AllocateChannels

int Mix_AllocateChannels(int numchans)

numchans
Number of channels to allocate for mixing.
A negative number will not do anything, it will tell you how many channels are currently allocated.

Set the number of channels being mixed. This can be called multiple times, even with sounds playing. If numchans is less than the current number of channels, then the higher channels will be stopped, freed, and therefore not mixed any longer. It's probably not a good idea to change the size 1000 times a second though.
If any channels are deallocated, any callback set by Mix_ChannelFinished will be called when each channel is halted to be freed. Note: passing in zero WILL free all mixing channels, however music will still play.

Returns: The number of channels allocated. Never fails...but a high number of channels can segfault if you run out of memory. We're talking REALLY high!

// allocate 16 mixing channels
Mix_AllocateChannels(16);

See Also:
4.1.4 Mix_OpenAudio

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3.2 Mix_Volume

int Mix_Volume(int channel, int volume)

channel
Channel to set mix volume for.
-1 will set the volume for all allocated channels.
volume
The volume to use from 0 to MIX_MAX_VOLUME(128).
If greater than MIX_MAX_VOLUME,
then it will be set to MIX_MAX_VOLUME.
If less than 0 then the volume will not be set.

Set the volume for any allocated channel. If channel is -1 then all channels at are set at once. The volume is applied during the final mix, along with the sample volume. So setting this volume to 64 will halve the output of all samples played on the specified channel. All channels default to a volume of 128, which is the max. Newly allocated channels will have the max volume set, so setting all channels volumes does not affect subsequent channel allocations.

Returns: current volume of the channel. If channel is -1, the average volume is returned.

// set channel 1 to half volume
Mix_Volume(1,MIX_MAX_VOLUME/2);

// print the average volume
printf("Average volume is %d\n",Mix_Volume(-1,-1));

See Also:
4.2.7 Mix_VolumeChunk, 4.5.9 Mix_VolumeMusic

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3.3 Mix_PlayChannel

int Mix_PlayChannel(int channel, Mix_Chunk *chunk, int loops)

channel
Channel to play on, or -1 for the first free unreserved channel.
chunk
Sample to play.
loops
Number of loops, -1 is infinite loops.
Passing one here plays the sample twice (1 loop).

Play chunk on channel, or if channel is -1, pick the first free unreserved channel. The sample will play for loops+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer.
Note: this just calls Mix_PlayChannelTimed() with ticks set to -1.

Returns: the channel the sample is played on. On any errors, -1 is returned.

// play sample on first free unreserved channel
// play it exactly once through
// Mix_Chunk *sample; //previously loaded
if(Mix_PlayChannel(-1, sample, 0)==-1) {
    printf("Mix_PlayChannel: %s\n",Mix_GetError());
    // may be critical error, or maybe just no channels were free.
    // you could allocated another channel in that case...
}

See Also:
4.3.4 Mix_PlayChannelTimed, 4.3.5 Mix_FadeInChannel, 4.3.9 Mix_HaltChannel, 4.3.10 Mix_ExpireChannel, 4.4.1 Mix_ReserveChannels

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3.4 Mix_PlayChannelTimed

int Mix_PlayChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ticks)

channel
Channel to play on, or -1 for the first free unreserved channel.
chunk
Sample to play.
loops
Number of loops, -1 is infinite loops.
Passing one here plays the sample twice (1 loop).
ticks
Millisecond limit to play sample, at most.
If not enough loops or the sample chunk is not long enough, then the sample may stop before this timeout occurs.
-1 means play forever.

If the sample is long enough and has enough loops then the sample will stop after ticks milliseconds. Otherwise this function is the same as 4.3.3 Mix_PlayChannel.

Returns: the channel the sample is played on. On any errors, -1 is returned.

// play sample on first free unreserved channel
// play it for half a second
// Mix_Chunk *sample; //previously loaded
if(Mix_PlayChannelTimed(-1, sample, -1 , 500)==-1) {
    printf("Mix_PlayChannel: %s\n",Mix_GetError());
    // may be critical error, or maybe just no channels were free.
    // you could allocated another channel in that case...
}

See Also:
4.3.3 Mix_PlayChannel, 4.3.6 Mix_FadeInChannelTimed, 4.3.11 Mix_FadeOutChannel, 4.4.1 Mix_ReserveChannels

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3.5 Mix_FadeInChannel

int Mix_FadeInChannel(int channel, Mix_Chunk *chunk, int loops, int ms)

channel
Channel to play on, or -1 for the first free unreserved channel.
chunk
Sample to play.
loops
Number of loops, -1 is infinite loops.
Passing one here plays the sample twice (1 loop).
ms
Milliseconds of time that the fade-in effect should take to go from silence to full volume.

Play chunk on channel, or if channel is -1, pick the first free unreserved channel.
The channel volume starts at 0 and fades up to full volume over ms milliseconds of time. The sample may end before the fade-in is complete if it is too short or doesn't have enough loops. The sample will play for loops+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer.
Note: this just calls Mix_FadeInChannelTimed() with ticks set to -1.

Returns: the channel the sample is played on. On any errors, -1 is returned.

// play sample on first free unreserved channel
// play it exactly 3 times through
// fade in over one second
// Mix_Chunk *sample; //previously loaded
if(Mix_FadeInChannel(-1, sample, 2, 1000)==-1) {
    printf("Mix_FadeInChannel: %s\n",Mix_GetError());
    // may be critical error, or maybe just no channels were free.
    // you could allocated another channel in that case...
}

See Also:
4.3.3 Mix_PlayChannel, 4.3.6 Mix_FadeInChannelTimed, 4.3.15 Mix_FadingChannel, 4.3.11 Mix_FadeOutChannel, 4.4.1 Mix_ReserveChannels

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3.6 Mix_FadeInChannelTimed

int Mix_FadeInChannelTimed(int channel, Mix_Chunk *chunk,
                           int loops, int ms, int ticks)

channel
Channel to play on, or -1 for the first free unreserved channel.
chunk
Sample to play.
loops
Number of loops, -1 is infinite loops.
Passing one here plays the sample twice (1 loop).
ms
Milliseconds of time that the fade-in effect should take to go from silence to full volume.
ticks
Millisecond limit to play sample, at most.
If not enough loops or the sample chunk is not long enough, then the sample may stop before this timeout occurs.
-1 means play forever.

If the sample is long enough and has enough loops then the sample will stop after ticks milliseconds. Otherwise this function is the same as 4.3.5 Mix_FadeInChannel.

Returns: the channel the sample is played on. On any errors, -1 is returned.

// play sample on first free unreserved channel
// play it for half a second
// Mix_Chunk *sample; //previously loaded
if(Mix_PlayChannelTimed(-1, sample, -1 , 500)==-1) {
    printf("Mix_PlayChannel: %s\n",Mix_GetError());
    // may be critical error, or maybe just no channels were free.
    // you could allocated another channel in that case...
}

See Also:
4.3.4 Mix_PlayChannelTimed, 4.3.5 Mix_FadeInChannel, 4.3.15 Mix_FadingChannel, 4.3.9 Mix_HaltChannel, 4.3.10 Mix_ExpireChannel, 4.4.1 Mix_ReserveChannels

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3.7 Mix_Pause

void Mix_Pause(int channel)

channel
Channel to pause on, or -1 for all channels.

Pause channel, or all playing channels if -1 is passed in. You may still halt a paused channel.
Note: Only channels which are actively playing will be paused.

// pause all sample playback
Mix_Pause(-1);

See Also:
4.3.8 Mix_Resume, 4.3.14 Mix_Paused, 4.3.9 Mix_HaltChannel

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3.8 Mix_Resume

void Mix_Resume(int channel)

channel
Channel to resume playing, or -1 for all channels.

Unpause channel, or all playing and paused channels if -1 is passed in.

// resume playback on all previously active channels
Mix_Resume(-1);

See Also:
4.3.7 Mix_Pause, 4.3.14 Mix_Paused

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3.9 Mix_HaltChannel

int Mix_HaltChannel(int channel)

channel
Channel to stop playing, or -1 for all channels.

Halt channel playback, or all channels if -1 is passed in.
Any callback set by Mix_ChannelFinished will be called.

Returns: always returns zero. (kinda silly)

// halt playback on all channels
Mix_HaltChannel(-1);

See Also:
4.3.10 Mix_ExpireChannel, 4.3.11 Mix_FadeOutChannel, 4.3.12 Mix_ChannelFinished

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3.10 Mix_ExpireChannel

int Mix_ExpireChannel(int channel, int ticks)

channel
Channel to stop playing, or -1 for all channels.
ticks
Millisecons until channel(s) halt playback.

Halt channel playback, or all channels if -1 is passed in, after ticks milliseconds. Any callback set by Mix_ChannelFinished will be called when the channel expires.

Returns: Number of channels set to expire. Whether or not they are active.

// halt playback on all channels in 2 seconds
Mix_ExpireChannel(-1, 2000);

See Also:
4.3.9 Mix_HaltChannel, 4.3.11 Mix_FadeOutChannel, 4.3.12 Mix_ChannelFinished

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3.11 Mix_FadeOutChannel

int Mix_FadeOutChannel(int channel, int ms)

channel
Channel to fade out, or -1 to fade all channels out.
ms
Milliseconds of time that the fade-out effect should take to go to silence, starting now.

Gradually fade out which channel over ms milliseconds starting from now. The channel will be halted after the fade out is completed. Only channels that are playing are set to fade out, including paused channels. Any callback set by Mix_ChannelFinished will be called when the channel finishes fading out.

Returns: The number of channels set to fade out.

// fade out all channels to finish 3 seconds from now
printf("starting fade out of %d channels\n", Mix_FadeOutChannel(-1, 3000));

See Also:
4.3.5 Mix_FadeInChannel, 4.3.6 Mix_FadeInChannelTimed, 4.3.15 Mix_FadingChannel, 4.3.12 Mix_ChannelFinished

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3.12 Mix_ChannelFinished

void Mix_ChannelFinished(void (*channel_finished)(int channel))

channel_finished
Function to call when any channel finishes playback.

When channel playback is halted, then the specified channel_finished function is called. The channel parameter will contain the channel number that has finished.
NOTE: NEVER call SDL_Mixer functions, nor SDL_LockAudio, from a callback function.

// a simple channel_finished function
void channelDone(int channel) {
    printf("channel %d finished playback.\n",channel);
}

// make a channelDone function
void channelDone(int channel)
{
    printf("channel %d finished playing.\n", channel);
}
...
// set the callback for when a channel stops playing
Mix_ChannelFinished(channelDone);

See Also:
4.3.9 Mix_HaltChannel, 4.3.10 Mix_ExpireChannel

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3.13 Mix_Playing

int Mix_Playing(int channel)

channel
Channel to test whether it is playing or not.
-1 will tell you how many channels are playing.

Tells you if channel is playing, or not.
Note: Does not check if the channel has been paused.

Returns: Zero if the channel is not playing. Otherwise if you passed in -1, the number of channels playing is returned. If you passed in a specific channel, then 1 is returned if it is playing.

// check how many channels are playing samples
printf("%d channels are playing\n", Mix_Playing(-1));

See Also:
4.3.14 Mix_Paused, 5.4 Mix_Fading, 4.3.3 Mix_PlayChannel, 4.3.7 Mix_Pause,

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3.14 Mix_Paused

int Mix_Paused(int channel)

channel
Channel to test whether it is paused or not.
-1 will tell you how many channels are paused.

Tells you if channel is paused, or not.
Note: Does not check if the channel has been halted after it was paused, which may seem a little weird.

Returns: Zero if the channel is not paused. Otherwise if you passed in -1, the number of paused channels is returned. If you passed in a specific channel, then 1 is returned if it is paused.

// check the pause status on all channels
printf("%d channels are paused\n", Mix_Paused(-1));

See Also:
4.3.13 Mix_Playing, 4.3.7 Mix_Pause, 4.3.8 Mix_Resume

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3.15 Mix_FadingChannel

Mix_Fading Mix_FadingChannel(int which)

which
Channel to get the fade activity status from.
-1 is not valid, and will probably crash the program.

Tells you if which channel is fading in, out, or not. Does not tell you if the channel is playing anything, or paused, so you'd need to test that separately.

Returns: the fading status. Never returns an error.

// check the fade status on channel 0
switch(Mix_FadingChannel(0)) {
    case MIX_NO_FADING:
        printf("Not fading.\n");
        break;
    case MIX_FADING_OUT:
        printf("Fading out.\n");
        break;
    case MIX_FADING_IN:
        printf("Fading in.\n");
        break;
}

See Also:
5.4 Mix_Fading, 4.3.13 Mix_Playing, 4.3.14 Mix_Paused, 4.3.5 Mix_FadeInChannel, 4.3.6 Mix_FadeInChannelTimed, 4.3.11 Mix_FadeOutChannel

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3.16 Mix_GetChunk

Mix_Chunk *Mix_GetChunk(int channel)

channel
Channel to get the current Mix_Chunk playing.
-1 is not valid, but will not crash the program.

Get the most recent sample chunk pointer played on channel. This pointer may be currently playing, or just the last used.
Note: The actual chunk may have been freed, so this pointer may not be valid anymore.

Returns: Pointer to the Mix_Chunk. NULL is returned if the channel is not allocated, or if the channel has not played any samples yet.

// get the last chunk used by channel 0
printf("Mix_Chunk* last in use on channel 0 was: %08p\n", Mix_GetChunk(0));

See Also:
5.1 Mix_Chunk, 4.3.13 Mix_Playing

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.4 Groups

These functions work with groupings of mixer channels.

The default group tag number of -1, which refers to ALL channels.

Setup
4.4.1 Mix_ReserveChannels Prevent channels from being used in default group
TODO
4.4.2 Mix_GroupChannel | Add/remove channel to/from group
4.4.3 Mix_GroupChannels | Add/remove segment of channels to/from group
Info
4.4.4 Mix_GroupCount | Get number of channels in group
4.4.5 Mix_GroupAvailable | Get first inactive channel in group
4.4.6 Mix_GroupOldest | Get oldest busy channel in group
4.4.7 Mix_GroupNewer | Get youngest busy channel in group
Stopping
4.4.8 Mix_FadeOutGroup | Fade out a group over time
4.4.9 Mix_HaltGroup | Stop a group

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.4.1 Mix_ReserveChannels

int Mix_ReserveChannels(int num)

num
Number of channels to reserve from default mixing.
Zero removes all reservations.

Reserve num channels from being used when playing samples when passing in -1 as a channel number to playback functions. The channels are reserved starting from channel 0 to num-1. Passing in zero will unreserve all channels. Normally SDL_mixer starts without any channels reserved.

The following functions are affected by this setting:
4.3.3 Mix_PlayChannel
4.3.4 Mix_PlayChannelTimed
4.3.5 Mix_FadeInChannel
4.3.6 Mix_FadeInChannelTimed

Returns: The number of channels reserved. Never fails, but may return less channels than you ask for, depending on the number of channels previously allocated.

// reserve the first 8 mixing channels
int reserved_count;
reserved_count=Mix_ReserveChannels(8);
if(reserved_count!=8) {
    printf("reserved %d channels from default mixing.\n",reserved_count);
    printf("8 channels were not reserved!\n");
    // this might be a critical error...
}

See Also:
4.3.1 Mix_AllocateChannels

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.4.2 Mix_GroupChannel

int Mix_GroupChannel(int which, int tag)

which
Channel number of channels to assign tag to.
tag
A group number Any positive numbers (including zero).
-1 is the default group. Use -1 to remove a group tag essentially.

Add which channel to group tag, or reset it's group to the default group tag (-1).

Returns: True(1) on success. False(0) is returned when the channel specified is invalid.

// add channel 0 to group 1
if(!Mix_GroupChannel(0,1)) {
    // bad channel, apparently channel 1 isn't allocated
}

See Also:
4.4.3 Mix_GroupChannels, 4.3.1 Mix_AllocateChannels

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.4.3 Mix_GroupChannels

int Mix_GroupChannels(int from, int to, int tag)

from
First Channel number of channels to assign tag to. Must be less or equal to to.
to
Last Channel number of channels to assign tag to. Must be greater or equal to from.
tag
A group number. Any positive numbers (including zero).
-1 is the default group. Use -1 to remove a group tag essentially.

Add channels starting at from up through to to group tag, or reset it's group to the default group tag (-1).

Returns: The number of tagged channels on success. If that number is less than to-from+1 then some channels were no tagged because they didn't exist.

// add channels 0 through 7 to group 1
if(Mix_GroupChannels(0,7,1)!=8) {
    // some bad channels, apparently some channels aren't allocated
}

See Also:
4.4.2 Mix_GroupChannel, 4.3.1 Mix_AllocateChannels

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.4.4 Mix_GroupCount

int Mix_GroupCount(int tag)

tag
A group number Any positive numbers (including zero).
-1 will count ALL channels.

Count the number of channels in group tag.

Returns: The number of channels found in the group. This function never fails.

// count the number of channels in group 1
printf("There are %d channels in group 1\n", Mix_GroupCount(1));

See Also:
4.4.2 Mix_GroupChannel, 4.4.3 Mix_GroupChannels

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.4.5 Mix_GroupAvailable

int Mix_GroupAvailable(int tag)

tag
A group number Any positive numbers (including zero).
-1 will search ALL channels.

Find the first available (not playing) channel in group tag.

Returns: The channel found on success. -1 is returned when no channels in the group are available.

// find the first available channel in group 1
int channel;
channel=Mix_GroupAvailable(1);
if (channel==-1) {
    // no channel available...
    // perhaps search for oldest or newest channel in use...
}

See Also:
4.4.6 Mix_GroupOldest, 4.4.7 Mix_GroupNewer, 4.4.2 Mix_GroupChannel, 4.4.3 Mix_GroupChannels

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.4.6 Mix_GroupOldest

int Mix_GroupOldest(int tag)

tag
A group number Any positive numbers (including zero).
-1 will search ALL channels.

Find the oldest actively playing channel in group tag.

Returns: The channel found on success. -1 is returned when no channels in the group are playing or the group is empty.

// find the oldest playing channel in group 1
int channel;
channel=Mix_GroupOldest(1);
if (channel==-1) {
    // no channel playing or allocated...
    // perhaps just search for an available channel...
}

See Also:
4.4.7 Mix_GroupNewer, 4.4.5 Mix_GroupAvailable, 4.4.2 Mix_GroupChannel, 4.4.3 Mix_GroupChannels

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.4.7 Mix_GroupNewer

int Mix_GroupNewer(int tag)

tag
A group number Any positive numbers (including zero).
-1 will search ALL channels.

Find the newest, most recently started, actively playing channel in group tag.

Returns: The channel found on success. -1 is returned when no channels in the group are playing or the group is empty.

// find the newest playing channel in group 1
int channel;
channel=Mix_GroupNewer(1);
if (channel==-1) {
    // no channel playing or allocated...
    // perhaps just search for an available channel...
}

See Also:
4.4.6 Mix_GroupOldest, 4.4.5 Mix_GroupAvailable, 4.4.2 Mix_GroupChannel, 4.4.3 Mix_GroupChannels

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.4.8 Mix_FadeOutGroup

int Mix_FadeOutGroup(int tag, int ms)

tag
Group to fade out.
NOTE: -1 will NOT fade all channels out. Use Mix_FadeOutChannel(-1) for that instead.
ms
Milliseconds of time that the fade-out effect should take to go to silence, starting now.

Gradually fade out channels in group tag over ms milliseconds starting from now. The channels will be halted after the fade out is completed. Only channels that are playing are set to fade out, including paused channels. Any callback set by Mix_ChannelFinished will be called when each channel finishes fading out.

Returns: The number of channels set to fade out.

// fade out all channels in group 1 to finish 3 seconds from now
printf("starting fade out of %d channels\n", Mix_FadeOutGroup(1, 3000));

See Also:
4.4.9 Mix_HaltGroup, 4.3.11 Mix_FadeOutChannel, 4.3.15 Mix_FadingChannel, 4.3.12 Mix_ChannelFinished

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.4.9 Mix_HaltGroup

int Mix_HaltGroup(int tag)

tag
Group to fade out.
NOTE: -1 will NOT halt all channels. Use Mix_HaltChannel(-1) for that instead.

Halt playback on all channels in group tag.
Any callback set by Mix_ChannelFinished will be called once for each channel that stops.

Returns: always returns zero. (more silly than Mix_HaltChannel)

// halt playback on all channels in group 1
Mix_HaltGroup(1);

See Also:
4.4.8 Mix_FadeOutGroup, 4.3.9 Mix_HaltChannel, 4.3.12 Mix_ChannelFinished

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5 Music

These functions work with music. Music is not played on a normal mixer channel. Music is therefore manipulated separately, except in post-processing hooks.

Loading
4.5.1 Mix_GetNumMusicDecoders | Number of music format types that can be decoded
4.5.2 Mix_GetMusicDecoder | Name of enumerated music format type decoder
4.5.3 Mix_LoadMUS | Load a music file into a Mix_Music
Free
4.5.4 Mix_FreeMusic Free a Mix_Music
Playing
4.5.5 Mix_PlayMusic | Play music, with looping
4.5.6 Mix_FadeInMusic | Play music, with looping, and fade in
4.5.7 Mix_FadeInMusicPos | Play music from a start point, with looping, and fade in
4.5.8 Mix_HookMusic | Hook for a custom music player
Settings
4.5.9 Mix_VolumeMusic | Set music volume
4.5.10 Mix_PauseMusic | Pause music
4.5.11 Mix_ResumeMusic | Resume paused music
4.5.12 Mix_RewindMusic | Rewind music to beginning
4.5.13 Mix_SetMusicPosition | Set position of playback in stream
4.5.14 Mix_SetMusicCMD | Use external program for music playback
Stopping
4.5.15 Mix_HaltMusic | Stop music playback
4.5.16 Mix_FadeOutMusic | Stop music, with fade out
4.5.17 Mix_HookMusicFinished | Set a callback for when music stops
Info
4.5.18 Mix_GetMusicType | Get the music encoding type
4.5.19 Mix_PlayingMusic | Test whether music is playing
4.5.20 Mix_PausedMusic | Test whether music is paused
4.5.21 Mix_FadingMusic | Get status of current music fade activity
4.5.22 Mix_GetMusicHookData | Retrieve the Mix_HookMusic arg

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.1 Mix_GetNumMusicDecoders

int Mix_GetNumMusicDecoders()

Get the number of music decoders available from the Mix_GetMusicDecoder function. This number can be different for each run of a program, due to the change in availability of shared libraries that support each format.

Returns: The number of music decoders available.

// print the number of music decoders available
printf("There are %d music deocoders available\n", Mix_GetNumMusicDecoders());

See Also:
4.2.1 Mix_GetNumChunkDecoders, 4.5.2 Mix_GetMusicDecoder, 4.5.3 Mix_LoadMUS

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.2 Mix_GetMusicDecoder

const char *Mix_GetMusicDecoder(int index)

index
The index number of music decoder to get.
In the range from 0(zero) to Mix_GetNumMusicDecoders()-1, inclusive.

Get the name of the indexed music decoder. You need to get the number of music decoders available using the Mix_GetNumMusicDecoders function.

Returns: The name of the indexed music decoder. This string is owned by the SDL_mixer library, do not modify or free it. It is valid until you call Mix_CloseAudio the final time.

// print music decoders available
int i,max=Mix_GetNumMusicDecoders();
for(i=0; i<max; ++i)
    printf("Music decoder %d is for %s",Mix_GetMusicDecoder(i));

See Also:
4.5.1 Mix_GetNumMusicDecoders, 4.2.2 Mix_GetChunkDecoder, 4.2.3 Mix_LoadWAV

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.3 Mix_LoadMUS

Mix_Music *Mix_LoadMUS(const char *file)

file
Name of music file to use.

Load music file to use. This can load WAVE, MOD, MIDI, OGG, MP3, FLAC, and any file that you use a command to play with.
If you are using an external command to play the music, you must call Mix_SetMusicCMD before this, otherwise the internal players will be used. Alternatively, if you have set an external command up and don't want to use it, you must call Mix_SetMusicCMD(NULL) to use the built-in players again.

Returns: A pointer to a Mix_Music. NULL is returned on errors.

// load the MP3 file "music.mp3" to play as music
Mix_Music *music;
music=Mix_LoadMUS("music.mp3");
if(!music) {
    printf("Mix_LoadMUS(\"music.mp3\"): %s\n", Mix_GetError());
    // this might be a critical error...
}

See Also:
5.2 Mix_Music, 4.5.14 Mix_SetMusicCMD, 4.5.5 Mix_PlayMusic, 4.5.6 Mix_FadeInMusic, 4.5.7 Mix_FadeInMusicPos

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.4 Mix_FreeMusic

void Mix_FreeMusic(Mix_Music *music)

music
Pointer to Mix_Music to free.

Free the loaded music. If music is playing it will be halted. If music is fading out, then this function will wait (blocking) until the fade out is complete.

// free music
Mix_Music *music;
Mix_FreeMusic(music);
music=NULL; // so we know we freed it...

See Also:
4.5.3 Mix_LoadMUS

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.5 Mix_PlayMusic

int Mix_PlayMusic(Mix_Music *music, int loops)

music
Pointer to Mix_Music to play.
loops
number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)

Play the loaded music loop times through from start to finish. The previous music will be halted, or if fading out it waits (blocking) for that to finish.

Returns: 0 on success, or -1 on errors.

// play music forever
// Mix_Music *music; // I assume this has been loaded already
if(Mix_PlayMusic(music, -1)==-1) {
    printf("Mix_PlayMusic: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
4.5.6 Mix_FadeInMusic

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.6 Mix_FadeInMusic

int Mix_FadeInMusic(Mix_Music *music, int loops, int ms)

music
Pointer to Mix_Music to play.
loops
number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)
ms
Milliseconds for the fade-in effect to complete.

Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish.
The fade in effect only applies to the first loop.
Any previous music will be halted, or if it is fading out it will wait (blocking) for the fade to complete.
This function is the same as Mix_FadeInMusicPos(music, loops, ms, 0).

Returns: 0 on success, or -1 on errors.

// play music forever, fading in over 2 seconds
// Mix_Music *music; // I assume this has been loaded already
if(Mix_FadeInMusic(music, -1, 2000)==-1) {
    printf("Mix_FadeInMusic: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
4.5.5 Mix_PlayMusic, 4.5.7 Mix_FadeInMusicPos

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.7 Mix_FadeInMusicPos

int Mix_FadeInMusicPos(Mix_Music *music, int loops, int ms, double position)

music
Pointer to Mix_Music to play.
loops
number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)
ms
Milliseconds for the fade-in effect to complete.
position
Posistion to play from, see Mix_SetMusicPosition for meaning.

Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish.
The fade in effect only applies to the first loop.
The first time the music is played, it posistion will be set to posistion, which means different things for different types of music files, see Mix_SetMusicPosition for more info on that.
Any previous music will be halted, or if it is fading out it will wait (blocking) for the fade to complete.

Returns: 0 on success, or -1 on errors.

// play music forever, fading in over 2 seconds
// Mix_Music *music; // I assume this has been loaded already
if(Mix_FadeInMusicPos(music, -1, 2000)==-1) {
    printf("Mix_FadeInMusic: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
4.5.5 Mix_PlayMusic, 4.5.6 Mix_FadeInMusic, 4.5.13 Mix_SetMusicPosition

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.8 Mix_HookMusic

void Mix_HookMusic(void (*mix_func)(void *udata, Uint8 *stream, int len),
                   void *arg)

mix_func
Function pointer to a music player mixer function.
NULL will stop the use of the music player, returning the mixer to using the internal music players like usual.
arg
This is passed to the mix_func's udata parameter when it is called.

This sets up a custom music player function. The function will be called with arg passed into the udata parameter when the mix_func is called. The stream parameter passes in the audio stream buffer to be filled with len bytes of music. The music player will then be called automatically when the mixer needs it. Music playing will start as soon as this is called. All the music playing and stopping functions have no effect on music after this. Pause and resume will work. Using a custom music player and the internal music player is not possible, the custom music player takes priority. To stop the custom music player call Mix_HookMusic(NULL, NULL).
NOTE: NEVER call SDL_Mixer functions, nor SDL_LockAudio, from a callback function.

// make a music play function
// it expects udata to be a pointer to an int
void myMusicPlayer(void *udata, Uint8 *stream, int len)
{
    int i, pos=*(int*)udata;

    // fill buffer with...uh...music...
    for(i=0; i<len; i++)
        stream[i]=(i+pos)&ff;

    // set udata for next time
    pos+=len;
    *(int*)udata=pos;
}
...
// use myMusicPlayer for playing...uh...music
int music_pos=0;
Mix_HookMusic(myMusicPlayer, &music_pos);

See Also:
4.5.14 Mix_SetMusicCMD, 4.5.22 Mix_GetMusicHookData

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.9 Mix_VolumeMusic

int Mix_VolumeMusic(int volume)

volume
Music volume, from 0 to MIX_MAX_VOLUME(128).
Values greater than MIX_MAX_VOLUME will use MIX_MAX_VOLUME.
-1 does not set the volume, but does return the current volume setting.

Set the volume to volume, if it is 0 or greater, and return the previous volume setting. Setting the volume during a fade will not work, the faders use this function to perform their effect! Setting volume while using an external music player set by Mix_SetMusicCMD will have no effect, and Mix_GetError will show the reason why not.

Returns: The previous volume setting.

// set the music volume to 1/2 maximum, and then check it
printf("volume was    : %d\n", Mix_VolumeMusic(MIX_MAX_VOLUME/2));
printf("volume is now : %d\n", Mix_VolumeMusic(-1));

See Also:
4.5.6 Mix_FadeInMusic, 4.5.16 Mix_FadeOutMusic, 4.5.14 Mix_SetMusicCMD

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.10 Mix_PauseMusic

void Mix_PauseMusic()

Pause the music playback. You may halt paused music.
Note: Music can only be paused if it is actively playing.

// pause music playback
Mix_PauseMusic();

See Also:
4.5.11 Mix_ResumeMusic, 4.5.20 Mix_PausedMusic, 4.5.15 Mix_HaltMusic

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.11 Mix_ResumeMusic

void Mix_ResumeMusic()

Unpause the music. This is safe to use on halted, paused, and already playing music.

// resume music playback
Mix_ResumeMusic();

See Also:
4.5.10 Mix_PauseMusic, 4.5.20 Mix_PausedMusic

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.12 Mix_RewindMusic

void Mix_RewindMusic()

Rewind the music to the start. This is safe to use on halted, paused, and already playing music. It is not useful to rewind the music immediately after starting playback, because it starts at the beginning by default.

This function only works for these streams: MOD, OGG, MP3, Native MIDI.

// rewind music playback to the start
Mix_RewindMusic();

See Also:
4.5.5 Mix_PlayMusic

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.13 Mix_SetMusicPosition

int Mix_SetMusicPosition(double position)

position
Posistion to play from.

Set the position of the currently playing music. The position takes different meanings for different music sources. It only works on the music sources listed below.

MOD
The double is cast to Uint16 and used for a pattern number in the module.
Passing zero is similar to rewinding the song.
OGG
Jumps to position seconds from the beginning of the song.
MP3
Jumps to position seconds from the current position in the stream.
So you may want to call Mix_RewindMusic before this.
Does not go in reverse...negative values do nothing.

Returns: 0 on success, or -1 if the codec doesn't support this function.

// skip one minute into the song, from the start
// this assumes you are playing an MP3
Mix_RewindMusic();
if(Mix_SetMusicPosition(60.0)==-1) {
    printf("Mix_SetMusicPosition: %s\n", Mix_GetError());
}

See Also:
4.5.7 Mix_FadeInMusicPos

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.14 Mix_SetMusicCMD

int Mix_SetMusicCMD(const char *command)

command
System command to play the music. Should be a complete command, as if typed in to the command line, but it should expect the filename to be added as the last argument.
NULL will turn off using an external command for music, returning to the internal music playing functionality.

Setup a command line music player to use to play music. Any music playing will be halted. The music file to play is set by calling Mix_LoadMUS(filename), and the filename is appended as the last argument on the commandline. This allows you to reuse the music command to play multiple files. The command will be sent signals SIGTERM to halt, SIGSTOP to pause, and SIGCONT to resume. The command program should react correctly to those signals for it to function properly with SDL_Mixer. Mix_VolumeMusic has no effect when using an external music player, and Mix_GetError will have an error code set. You should set the music volume in the music player's command if the music player supports that. Looping music works, by calling the command again when the previous music player process has ended. Playing music through a command uses a forked process to execute the music command.
To use the internal music players set the command to NULL.
NOTE: External music is not mixed by SDL_mixer, so no post-processing hooks will be for music.
NOTE: Playing music through an external command may not work if the sound driver does not support multiple openings of the audio device, since SDL_Mixer already has the audio device open for playing samples through channels.
NOTE: Commands are not totally portable, so be careful.

Returns: 0 on success, or -1 on any errors, such as running out of memory.

// use mpg123 to play music
Mix_Music *music=NULL;
if(Mix_SetMusicCMD("mpg123 -q")==-1) {
    perror("Mix_SetMusicCMD");
} else {
    // play some mp3 file
    music=Mix_LoadMUS("music.mp3");
    if(music) {
        Mix_PlayMusic(music,1);
    }
}

See Also:
4.5.5 Mix_PlayMusic, 4.5.9 Mix_VolumeMusic

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.15 Mix_HaltMusic

int Mix_HaltMusic()

Halt playback of music. This interrupts music fader effects. Any callback set by Mix_HookMusicFinished will be called when the music stops.

Returns: always returns zero. (even more silly than Mix_HaltGroup)

// halt music playback
Mix_HaltMusic();

See Also:
4.5.16 Mix_FadeOutMusic, 4.5.17 Mix_HookMusicFinished

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.16 Mix_FadeOutMusic

int Mix_FadeOutMusic(int ms)

ms
Milliseconds of time that the fade-out effect should take to go to silence, starting now.

Gradually fade out the music over ms milliseconds starting from now. The music will be halted after the fade out is completed. Only when music is playing and not fading already are set to fade out, including paused channels. Any callback set by Mix_HookMusicFinished will be called when the music finishes fading out.

Returns: 1 on success, 0 on failure.

// fade out music to finish 3 seconds from now
while(!Mix_FadeOutMusic(3000) && Mix_PlayingMusic()) {
    // wait for any fades to complete
    SDL_Delay(100);
}

See Also:
4.5.15 Mix_HaltMusic, 4.5.21 Mix_FadingMusic, 4.5.19 Mix_PlayingMusic, 4.5.17 Mix_HookMusicFinished

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.17 Mix_HookMusicFinished

void Mix_HookMusicFinished(void (*music_finished)())

music_finished
Function pointer to a void function().
NULL will remove the hook.

This sets up a function to be called when music playback is halted. Any time music stops, the music_finished function will be called. Call with NULL to remove the callback.
NOTE: NEVER call SDL_Mixer functions, nor SDL_LockAudio, from a callback function.

// make a music finished function
void musicFinished()
{
    printf("Music stopped.\n");
}
...
// use musicFinished for when music stops
Mix_HookMusicFinished(musicFinished);

See Also:
4.5.15 Mix_HaltMusic, 4.5.16 Mix_FadeOutMusic

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.18 Mix_GetMusicType

Mix_MusicType Mix_GetMusicType(const Mix_Music *music)

music
The music to get the type of.
NULL will get the currently playing music type.

Tells you the file format encoding of the music. This may be handy when used with Mix_SetMusicPosition, and other music functions that vary based on the type of music being played. If you want to know the type of music currently being played, pass in NULL to music.

Returns: The type of music or if music is NULL then the currently playing music type, otherwise MUS_NONE if no music is playing.

// print the type of music currently playing
switch(Mix_GetMusicType(NULL))
{
    case MUS_NONE:
    MUS_CMD:
        printf("Command based music is playing.\n");
        break;
    MUS_WAV:
        printf("WAVE/RIFF music is playing.\n");
        break;
    MUS_MOD:
        printf("MOD music is playing.\n");
        break;
    MUS_MID:
        printf("MIDI music is playing.\n");
        break;
    MUS_OGG:
        printf("OGG music is playing.\n");
        break;
    MUS_MP3:
        printf("MP3 music is playing.\n");
        break;
    default:
        printf("Unknown music is playing.\n");
        break;
}

See Also:
5.3 Mix_MusicType, 4.6.7 Mix_SetPosition

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.19 Mix_PlayingMusic

int Mix_PlayingMusic()

Tells you if music is actively playing, or not.
Note: Does not check if the channel has been paused.

Returns: Zero if the music is not playing, or 1 if it is playing.

// check if music is playing
printf("music is%s playing.\n", Mix_PlayingMusic()?"":" not");

See Also:
4.5.20 Mix_PausedMusic, 4.5.21 Mix_FadingMusic, 4.5.5 Mix_PlayMusic

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.20 Mix_PausedMusic

int Mix_PausedMusic()

Tells you if music is paused, or not.
Note: Does not check if the music was been halted after it was paused, which may seem a little weird.

Returns: Zero if music is not paused. 1 if it is paused.

// check the music pause status
printf("music is%s paused\n", Mix_PausedMusic()?"":" not");

See Also:
4.5.19 Mix_PlayingMusic, 4.5.10 Mix_PauseMusic, 4.5.11 Mix_ResumeMusic

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.21 Mix_FadingMusic

Mix_Fading Mix_FadingMusic()

Tells you if music is fading in, out, or not at all. Does not tell you if the channel is playing anything, or paused, so you'd need to test that separately.

Returns: the fading status. Never returns an error.

// check the music fade status
switch(Mix_FadingMusic()) {
    case MIX_NO_FADING:
        printf("Not fading music.\n");
        break;
    case MIX_FADING_OUT:
        printf("Fading out music.\n");
        break;
    case MIX_FADING_IN:
        printf("Fading in music.\n");
        break;
}

See Also:
5.4 Mix_Fading, 4.5.20 Mix_PausedMusic, 4.5.19 Mix_PlayingMusic, 4.5.7 Mix_FadeInMusicPos, 4.5.16 Mix_FadeOutMusic

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5.22 Mix_GetMusicHookData

void *Mix_GetMusicHookData()

Get the arg passed into Mix_HookMusic.

Returns: the arg pointer.

// retrieve the music hook data pointer
void *data;
data=Mix_GetMusicHookData();

See Also:
4.5.8 Mix_HookMusic

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.6 Effects

These functions are for special effects processing. Not all effects are all that special. All effects are post processing routines that are either built-in to SDL_mixer or created by you. Effects can be applied to individual channels, or to the final mixed stream which contains all the channels including music.

Registration
4.6.1 Mix_RegisterEffect | Hook a processor to a channel
4.6.2 Mix_UnregisterEffect | Unhook a processor from a channel
4.6.3 Mix_UnregisterAllEffects | Unhook all processors from a channel
4.6.4 Mix_SetPostMix | Hook in a postmix processor
Built-in Processors
4.6.5 Mix_SetPanning | Stereo panning
4.6.6 Mix_SetDistance | Distance attenuation (volume)
4.6.7 Mix_SetPosition | Panning(angular) and distance
4.6.8 Mix_SetReverseStereo | Swap stereo left and right

The built-in processors: Mix_SetPanning, Mix_SetPosition, Mix_SetDistance, and
Mix_SetReverseStereo, all look for an environment variable, MIX_EFFECTSMAXSPEED to be defined. If the environment variable is defined these processors may use more memory or reduce the quality of the effects, all for better speed.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.6.1 Mix_RegisterEffect

int Mix_RegisterEffect(int chan, Mix_EffectFunc_t f, Mix_EffectDone_t d,
                       void *arg)

chan
channel number to register f and d on.
Use MIX_CHANNEL_POST to process the postmix stream.
f
The function pointer for the effects processor.
d
The function pointer for any cleanup routine to be called when the channel is done playing a sample.
This may be NULL for any processors that don't need to clean up any memory or other dynamic data.
arg
A pointer to data to pass into the f's and d's udata parameter. It is a good place to keep the state data for the processor, especially if the processor is made to handle multiple channels at the same time.
This may be NULL, depending on the processor.

Hook a processor function f into a channel for post processing effects. You may just be reading the data and displaying it, or you may be altering the stream to add an echo. Most processors also have state data that they allocate as they are in use, this would be stored in the arg pointer data space. When a processor is finished being used, any function passed into d will be called, which is when your processor should clean up the data in the arg data space.
The effects are put into a linked list, and always appended to the end, meaning they always work on previously registered effects output. Effects may be added multiple times in a row. Effects are cumulative this way.

Returns: Zero on errors, such as a nonexisting channel.

// make a passthru processor function that does nothing...
void noEffect(int chan, void *stream, int len, void *udata)
{
    // you could work with stream here...
}
...
// register noEffect as a postmix processor
if(!Mix_RegisterEffect(MIX_CHANNEL_POST, noEffect, NULL, NULL)) {
    printf("Mix_RegisterEffect: %s\n", Mix_GetError());
}

See Also:
4.6.2 Mix_UnregisterEffect, 4.6.3 Mix_UnregisterAllEffects

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.6.2 Mix_UnregisterEffect

int Mix_UnregisterEffect(int channel, Mix_EffectFunc_t f)

channel
Channel number to remove f from as a post processor.
Use MIX_CHANNEL_POST for the postmix stream.
f
The function to remove from channel.

Remove the oldest (first found) registered effect function f from the effect list for channel. This only removes the first found occurance of that function, so it may need to be called multiple times if you added the same function multiple times, just stop removing when Mix_UnregisterEffect returns an error, to remove all occurances of f from a channel.
If the channel is active the registered effect will have its Mix_EffectDone_t function called, if it was specified in Mix_RegisterEffect.

Returns: Zero on errors, such as invalid channel, or effect function not registered on channel.

// unregister the noEffect from the postmix effects
// this removes all occurances of noEffect registered to the postmix
while(Mix_UnregisterEffect(MIX_CHANNEL_POST, noEffect));
// you may print Mix_GetError() if you want to check it.
// it should say "No such effect registered" after this loop.

See Also:
4.6.3 Mix_UnregisterAllEffects, 4.6.1 Mix_RegisterEffect

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.6.3 Mix_UnregisterAllEffects

int Mix_UnregisterAllEffects(int channel)

channel
Channel to remove all effects from.
Use MIX_CHANNEL_POST for the postmix stream.

This removes all effects registered to channel. If the channel is active all the registered effects will have their Mix_EffectDone_t functions called, if they were specified in Mix_RegisterEffect.

Returns: Zero on errors, such as channel not existing.

// remove all effects from channel 0
if(!Mix_UnregisterAllEffects(0)) {
    printf("Mix_UnregisterAllEffects: %s\n", Mix_GetError());
}

See Also:
4.6.2 Mix_UnregisterEffect, 4.6.1 Mix_RegisterEffect

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.6.4 Mix_SetPostMix

void Mix_SetPostMix(void (*mix_func)(void *udata, Uint8 *stream, int len),
                    void *arg)

mix_func
The function pointer for the postmix processor.
NULL unregisters the current postmixer.
arg
A pointer to data to pass into the mix_func's udata parameter. It is a good place to keep the state data for the processor, especially if the processor is made to handle multiple channels at the same time.
This may be NULL, depending on the processor.

Hook a processor function mix_func to the postmix stream for post processing effects. You may just be reading the data and displaying it, or you may be altering the stream to add an echo. Most processors also have state data that they allocate as they are in use, this would be stored in the arg pointer data space. This processor is never really finished, until the audio device is closed, or you pass NULL as the mix_func.
There can only be one postmix function used at a time through this method. Use Mix_RegisterEffect(MIX_CHANNEL_POST, mix_func, NULL, arg) to use multiple postmix processors.
This postmix processor is run AFTER all the registered postmixers set up by Mix_RegisterEffect.

// make a passthru processor function that does nothing...
void noEffect(void *udata, Uint8 *stream, int len)
{
    // you could work with stream here...
}
...
// register noEffect as a postmix processor
Mix_SetPostMix(noEffect, NULL);

See Also:
4.6.1 Mix_RegisterEffect

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.6.5 Mix_SetPanning

int Mix_SetPanning(int channel, Uint8 left, Uint8 right)

channel
Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream.
left
Volume for the left channel, range is 0(silence) to 255(loud)
right
Volume for the left channel, range is 0(silence) to 255(loud)

This effect will only work on stereo audio. Meaning you called Mix_OpenAudio with 2 channels (MIX_DEFAULT_CHANNELS). The easiest way to do true panning is to call Mix_SetPanning(channel, left, 254 - left); so that the total volume is correct, if you consider the maximum volume to be 127 per channel for center, or 254 max for left, this works, but about halves the effective volume.
This Function registers the effect for you, so don't try to Mix_RegisterEffect it yourself.
NOTE: Setting both left and right to 255 will unregister the effect from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.
NOTE: Using this function on a mono audio device will not register the effect, nor will it return an error status.

Returns: Zero on errors, such as bad channel, or if Mix_RegisterEffect failed.

// pan channel 1 halfway to the left
if(!Mix_SetPanning(1, 255, 127)) {
    printf("Mix_SetPanning: %s\n", Mix_GetError());
    // no panning, is it ok?
}

See Also:
4.6.7 Mix_SetPosition, 4.6.3 Mix_UnregisterAllEffects

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.6.6 Mix_SetDistance

int Mix_SetDistance(int channel, Uint8 distance)

channel
Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream.
distance
Specify the distance from the listener, from 0(close/loud) to 255(far/quiet).

This effect simulates a simple attenuation of volume due to distance. The volume never quite reaches silence, even at max distance.
NOTE: Using a distance of 0 will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.

Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect failed.

// distance channel 1 to be farthest away
if(!Mix_SetDistance(1, 255)) {
    printf("Mix_SetDistance: %s\n", Mix_GetError());
    // no distance, is it ok?
}

See Also:
4.6.7 Mix_SetPosition, 4.6.3 Mix_UnregisterAllEffects

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.6.7 Mix_SetPosition

int Mix_SetPosition(int channel, Sint16 angle, Uint8 distance)

channel
Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream.
angle
Direction in relation to forward from 0 to 360 degrees. Larger angles will be reduced to this range using angles % 360.
0 = directly in front.
90 = directly to the right.
180 = directly behind.
270 = directly to the left.
So you can see it goes clockwise starting at directly in front.
This ends up being similar in effect to Mix_SetPanning.
distance
The distance from the listener, from 0(near/loud) to 255(far/quiet).
This is the same as the Mix_SetDistance effect.

This effect emulates a simple 3D audio effect. It's not all that realistic, but it can help improve some level of realism. By giving it the angle and distance from the camera's point of view, the effect pans and attenuates volumes. If you are looking for better positional audio, using OpenAL is suggested.
NOTE: Using angle and distance of 0, will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.

Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect failed.

// set channel 2 to be behind and right, and 100 units away
if(!Mix_SetPosition(2, 135, 100)) {
    printf("Mix_SetPosition: %s\n", Mix_GetError());
    // no position effect, is it ok?
}

See Also:
4.6.5 Mix_SetPanning, 4.6.6 Mix_SetDistance, 4.6.3 Mix_UnregisterAllEffects

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.6.8 Mix_SetReverseStereo

int Mix_SetReverseStereo(int channel, int flip)

channel
Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream.
flip
Must be non-zero to work, means nothing to the effect processor itself.
set to zero to unregister the effect from channel.

Simple reverse stereo, swaps left and right channel sound.
NOTE: Using a flip of 0, will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.

Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect failed.

// set the total mixer output to be reverse stereo
if(!Mix_SetReverseStereo(MIX_CHANNEL_POST, 1)) {
    printf("Mix_SetReverseStereo: %s\n", Mix_GetError());
    // no reverse stereo, is it ok?
}

See Also:
4.6.3 Mix_UnregisterAllEffects

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5. Types

These types are defined and used by the SDL_mixer API.

5.1 Mix_Chunk | The internal format for an audio chunk
5.2 Mix_Music | The internal format for a music chunk
5.3 Mix_MusicType | Music type enumerations
5.4 Mix_Fading | Fader effect type enumerations
5.5 Mix_EffectFunc_t | Special effect callback function pointer
5.6 Mix_EffectDone_t | Special effect done callback function pointer

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.1 Mix_Chunk

typedef struct Mix_Chunk {
    int allocated;
    Uint8 *abuf;
    Uint32 alen;
    Uint8 volume;     /* Per-sample volume, 0-128 */
} Mix_Chunk;

allocated
a boolean indicating whether to free abuf when the chunk is freed.
0 if the memory was not allocated and thus not owned by this chunk.
1 if the memory was allocated and is thus owned by this chunk.
abuf
Pointer to the sample data, which is in the output format and sample rate.
alen
Length of abuf in bytes.
volume
0 = silent, 128 = max volume. This takes effect when mixing.

The internal format for an audio chunk. This stores the sample data, the length in bytes of that data, and the volume to use when mixing the sample.

See Also:
4.2.7 Mix_VolumeChunk, 4.3.16 Mix_GetChunk, 4.2.3 Mix_LoadWAV, 4.2.4 Mix_LoadWAV_RW, 4.2.8 Mix_FreeChunk, 5.2 Mix_Music

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.2 Mix_Music

typedef struct _Mix_Music Mix_Music;

This is an opaque data type used for Music data. This should always be used as a pointer. Who knows why it isn't a pointer in this typedef...

See Also:
4.5.3 Mix_LoadMUS, 4.5.4 Mix_FreeMusic, 5.1 Mix_Chunk

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.3 Mix_MusicType

typedef enum {
    MUS_NONE,
    MUS_CMD,
    MUS_WAV,
    MUS_MOD,
    MUS_MID,
    MUS_OGG,
    MUS_MP3, /* using SMPEG */
    MUS_MP3_MAD,
    MUS_FLAC
} Mix_MusicType;

Return values from Mix_GetMusicType are of these enumerated values.
If no music is playing then MUS_NONE is returned.
If music is playing via an external command then MUS_CMD is returned.
Otherwise they are self explanatory.

See Also:
4.5.18 Mix_GetMusicType

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.4 Mix_Fading

typedef enum {
    MIX_NO_FADING,
    MIX_FADING_OUT,
    MIX_FADING_IN
} Mix_Fading;

Return values from Mix_FadingMusic and Mix_FadingChannel are of these enumerated values. If no fading is taking place on the queried channel or music, then MIX_NO_FADING is returned. Otherwise they are self explanatory.

See Also:
4.3.15 Mix_FadingChannel, 4.5.21 Mix_FadingMusic

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.5 Mix_EffectFunc_t

typedef void (*Mix_EffectFunc_t)(int chan, void *stream, int len,
                                 void *udata);

chan
The channel number that this effect is effecting now.
MIX_CHANNEL_POST is passed in for post processing effects over the final mix.
stream
The buffer containing the current sample to process.
len
The length of stream in bytes.
udata
User data pointer that was passed in to Mix_RegisterEffect when registering this effect processor function.

This is the prototype for effect processing functions. These functions are used to apply effects processing on a sample chunk. As a channel plays a sample, the registered effect functions are called. Each effect would then read and perhaps alter the len bytes of stream. It may also be advantageous to keep the effect state in the udata, with would be setup when registering the effect function on a channel.

See Also:
4.6.1 Mix_RegisterEffect 4.6.2 Mix_UnregisterEffect

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5.6 Mix_EffectDone_t

typedef void (*Mix_EffectDone_t)(int chan, void *udata);

chan
The channel number that this effect is effecting now.
MIX_CHANNEL_POST is passed in for post processing effects over the final mix.
udata
User data pointer that was passed in to Mix_RegisterEffect when registering this effect processor function.

This is the prototype for effect processing functions. This is called when a channel has finished playing, or halted, or is deallocated. This is also called when a processor is unregistered while processing is active. At that time the effects processing function may want to reset some internal variables or free some memory. It should free memory at least, because the processor could be freed after this call.

See Also:
4.6.1 Mix_RegisterEffect 4.6.2 Mix_UnregisterEffect

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6. Defines

SDL_MIXER_MAJOR_VERSION
1
SDL_mixer library major number at compilation time
SDL_MIXER_MINOR_VERSION
2
SDL_mixer library minor number at compilation time
SDL_MIXER_PATCHLEVEL
9
SDL_mixer library patch level at compilation time
MIX_CHANNELS
8
The default mixer has this many simultaneous mixing channels after the first call to Mix_OpenAudio.
MIX_DEFAULT_FREQUENCY
22050
Good default sample rate in Hz (samples per second) for PC sound cards.
MIX_DEFAULT_FORMAT
AUDIO_S16SYS
The suggested default is signed 16bit samples in host byte order.
MIX_DEFAULT_CHANNELS
2
Stereo sound is a good default.
MIX_MAX_VOLUME
128
Maximum value for any volume setting.
This is currently the same as SDL_MIX_MAXVOLUME.
MIX_CHANNEL_POST
-2
This is the channel number used for post processing effects.
MIX_EFFECTSMAXSPEED
"MIX_EFFECTSMAXSPEED"
A convience definition for the string name of the environment variable to define when you desire the internal effects to sacrifice quality and/or RAM for speed. The environment variable must be set (else nonexisting) before Mix_OpenAudio is called for the setting to take effect.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

7. Glossary

Byte Order
Also known as Big-Endian. Which means the most significant byte comes first in storage. Sparc and Motorola 68k based chips are MSB ordered.
(SDL defines this as SDL_BYTEORDER==SDL_BIG_ENDIAN)

Little-Endian(LSB) is stored in the opposite order, with the least significant byte first in memory. Intel and AMD are two LSB machines.
(SDL defines this as SDL_BYTEORDER==SDL_LIL_ENDIAN)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Index

Jump to: B L M R S

 | Index Entry | Section
B |  |
 | Big-Endian | 7. Glossary
 | Byte Order | 7. Glossary
L |  |
 | Little-Endian | 7. Glossary
 | LSB | 7. Glossary
M |  |
 | Mix_AllocateChannels | 4.3.1 Mix_AllocateChannels
 | MIX_CHANNEL_POST | 6. Defines
 | Mix_ChannelFinished | 4.3.12 Mix_ChannelFinished
 | MIX_CHANNELS | 6. Defines
 | Mix_Chunk | 4.2 Samples
 | Mix_Chunk | 5.1 Mix_Chunk
 | Mix_CloseAudio | 4.1.5 Mix_CloseAudio
 | MIX_DEFAULT_CHANNELS | 6. Defines
 | MIX_DEFAULT_FORMAT | 6. Defines
 | MIX_DEFAULT_FREQUENCY | 6. Defines
 | Mix_EffectDone_t | 5.6 Mix_EffectDone_t
 | Mix_EffectFunc_t | 5.5 Mix_EffectFunc_t
 | MIX_EFFECTSMAXSPEED | 6. Defines
 | Mix_ExpireChannel | 4.3.10 Mix_ExpireChannel
 | Mix_FadeInChannel | 4.3.5 Mix_FadeInChannel
 | Mix_FadeInChannel | 4.4.1 Mix_ReserveChannels
 | Mix_FadeInChannelTimed | 4.3.6 Mix_FadeInChannelTimed
 | Mix_FadeInChannelTimed | 4.4.1 Mix_ReserveChannels
 | Mix_FadeInMusic | 4.5.6 Mix_FadeInMusic
 | Mix_FadeInMusicPos | 4.5.7 Mix_FadeInMusicPos
 | Mix_FadeOutChannel | 4.3.11 Mix_FadeOutChannel
 | Mix_FadeOutGroup | 4.4.8 Mix_FadeOutGroup
 | Mix_FadeOutMusic | 4.5.16 Mix_FadeOutMusic
 | Mix_Fading | 5.4 Mix_Fading
 | Mix_FadingChannel | 4.3.15 Mix_FadingChannel
 | Mix_FadingMusic | 4.5.21 Mix_FadingMusic
 | Mix_FreeChunk | 4.2.8 Mix_FreeChunk
 | Mix_FreeMusic | 4.5.4 Mix_FreeMusic
 | Mix_GetChunk | 4.3.16 Mix_GetChunk
 | Mix_GetChunkDecoder | 4.2.2 Mix_GetChunkDecoder
 | Mix_GetError | 4.1.7 Mix_GetError
 | Mix_GetMusicDecoder | 4.5.2 Mix_GetMusicDecoder
 | Mix_GetMusicHookData | 4.5.22 Mix_GetMusicHookData
 | Mix_GetMusicType | 4.5.18 Mix_GetMusicType
 | Mix_GetNumChunkDecoders | 4.2.1 Mix_GetNumChunkDecoders
 | Mix_GetNumMusicDecoders | 4.5.1 Mix_GetNumMusicDecoders
 | Mix_GroupAvailable | 4.4.5 Mix_GroupAvailable
 | Mix_GroupChannel | 4.4.2 Mix_GroupChannel
 | Mix_GroupChannels | 4.4.3 Mix_GroupChannels
 | Mix_GroupCount | 4.4.4 Mix_GroupCount
 | Mix_GroupNewer | 4.4.7 Mix_GroupNewer
 | Mix_GroupOldest | 4.4.6 Mix_GroupOldest
 | Mix_HaltChannel | 4.3.9 Mix_HaltChannel
 | Mix_HaltGroup | 4.4.9 Mix_HaltGroup
 | Mix_HaltMusic | 4.5.15 Mix_HaltMusic
 | Mix_HookMusic | 4.5.8 Mix_HookMusic
 | Mix_HookMusicFinished | 4.5.17 Mix_HookMusicFinished
 | Mix_Init | 4.1.2 Mix_Init
 | Mix_Linked_Version | 4.1.1 Mix_Linked_Version
 | Mix_LoadMUS | 4.5.3 Mix_LoadMUS
 | Mix_LoadWAV | 4.2.3 Mix_LoadWAV
 | Mix_LoadWAV_RW | 4.2.4 Mix_LoadWAV_RW
 | MIx_MAJOR_VERSION | 6. Defines
 | MIX_MAX_VOLUME | 6. Defines
 | MIX_MINOR_VERSION | 6. Defines
 | Mix_Music | 5.2 Mix_Music
 | Mix_MusicType | 5.3 Mix_MusicType
 | Mix_OpenAudio | 4.1.4 Mix_OpenAudio
 | MIX_PATCHLEVEL | 6. Defines
 | Mix_Pause | 4.3.7 Mix_Pause
 | Mix_Paused | 4.3.14 Mix_Paused
 | Mix_PausedMusic | 4.5.20 Mix_PausedMusic
 | Mix_PauseMusic | 4.5.10 Mix_PauseMusic
 | Mix_PlayChannel | 4.3.3 Mix_PlayChannel
 | Mix_PlayChannel | 4.4.1 Mix_ReserveChannels
 | Mix_PlayChannelTimed | 4.3.4 Mix_PlayChannelTimed
 | Mix_PlayChannelTimed | 4.4.1 Mix_ReserveChannels
 | Mix_Playing | 4.3.13 Mix_Playing
 | Mix_PlayingMusic | 4.5.19 Mix_PlayingMusic
 | Mix_PlayMusic | 4.5.5 Mix_PlayMusic
 | Mix_QuerySpec | 4.1.8 Mix_QuerySpec
 | Mix_QuickLoad_RAW | 4.2.6 Mix_QuickLoad_RAW
 | Mix_QuickLoad_WAV | 4.2.5 Mix_QuickLoad_WAV
 | Mix_Quit | 4.1.3 Mix_Quit
 | Mix_RegisterEffect | 4.6.1 Mix_RegisterEffect
 | Mix_ReserveChannels | 4.4.1 Mix_ReserveChannels
 | Mix_Resume | 4.3.8 Mix_Resume
 | Mix_ResumeMusic | 4.5.11 Mix_ResumeMusic
 | Mix_RewindMusic | 4.5.12 Mix_RewindMusic
 | Mix_SetDistance | 4.6.6 Mix_SetDistance
 | Mix_SetError | 4.1.6 Mix_SetError
 | Mix_SetMusicCMD | 4.5.14 Mix_SetMusicCMD
 | Mix_SetMusicPosition | 4.5.13 Mix_SetMusicPosition
 | Mix_SetPanning | 4.6.5 Mix_SetPanning
 | Mix_SetPosition | 4.6.7 Mix_SetPosition
 | Mix_SetPostMix | 4.6.4 Mix_SetPostMix
 | Mix_SetReverseStereo | 4.6.8 Mix_SetReverseStereo
 | Mix_UnregisterAllEffects | 4.6.3 Mix_UnregisterAllEffects
 | Mix_UnregisterEffect | 4.6.2 Mix_UnregisterEffect
 | Mix_Volume | 4.3.2 Mix_Volume
 | Mix_VolumeChunk | 4.2.7 Mix_VolumeChunk
 | Mix_VolumeMusic | 4.5.9 Mix_VolumeMusic
 | MSB | 7. Glossary
R |  |
 | README | 1. Overview
S |  |
 | sdl-config | 2.2 Compiling
 | SDL_AudioDriverName | 3. Conflicts
 | SDL_CloseAudio | 3. Conflicts
 | SDL_GetAudioStatus | 3. Conflicts
 | SDL_LockAudio | 3. Conflicts
 | SDL_MIXER_MAJOR_VERSION | 6. Defines
 | SDL_MIXER_MINOR_VERSION | 6. Defines
 | SDL_MIXER_PATCHLEVEL | 6. Defines
 | SDL_MIXER_VERSION | 4.1.1 Mix_Linked_Version
 | SDL_OpenAudio | 3. Conflicts
 | SDL_PauseAudio | 3. Conflicts
 | SDL_UnlockAudio | 3. Conflicts

Jump to: B L M R S

[Top] [Contents] [Index] [ ? ]

Table of Contents

    1. Overview
    2. Getting Started
      2.1 Includes
      2.2 Compiling
    3. Conflicts
    4. Functions
      4.1 General
        4.1.1 Mix_Linked_Version
        4.1.2 Mix_Init
        4.1.3 Mix_Quit
        4.1.4 Mix_OpenAudio
        4.1.5 Mix_CloseAudio
        4.1.6 Mix_SetError
        4.1.7 Mix_GetError
        4.1.8 Mix_QuerySpec
      4.2 Samples
        4.2.1 Mix_GetNumChunkDecoders
        4.2.2 Mix_GetChunkDecoder
        4.2.3 Mix_LoadWAV
        4.2.4 Mix_LoadWAV_RW
        4.2.5 Mix_QuickLoad_WAV
        4.2.6 Mix_QuickLoad_RAW
        4.2.7 Mix_VolumeChunk
        4.2.8 Mix_FreeChunk
      4.3 Channels
        4.3.1 Mix_AllocateChannels
        4.3.2 Mix_Volume
        4.3.3 Mix_PlayChannel
        4.3.4 Mix_PlayChannelTimed
        4.3.5 Mix_FadeInChannel
        4.3.6 Mix_FadeInChannelTimed
        4.3.7 Mix_Pause
        4.3.8 Mix_Resume
        4.3.9 Mix_HaltChannel
        4.3.10 Mix_ExpireChannel
        4.3.11 Mix_FadeOutChannel
        4.3.12 Mix_ChannelFinished
        4.3.13 Mix_Playing
        4.3.14 Mix_Paused
        4.3.15 Mix_FadingChannel
        4.3.16 Mix_GetChunk
      4.4 Groups
        4.4.1 Mix_ReserveChannels
        4.4.2 Mix_GroupChannel
        4.4.3 Mix_GroupChannels
        4.4.4 Mix_GroupCount
        4.4.5 Mix_GroupAvailable
        4.4.6 Mix_GroupOldest
        4.4.7 Mix_GroupNewer
        4.4.8 Mix_FadeOutGroup
        4.4.9 Mix_HaltGroup
      4.5 Music
        4.5.1 Mix_GetNumMusicDecoders
        4.5.2 Mix_GetMusicDecoder
        4.5.3 Mix_LoadMUS
        4.5.4 Mix_FreeMusic
        4.5.5 Mix_PlayMusic
        4.5.6 Mix_FadeInMusic
        4.5.7 Mix_FadeInMusicPos
        4.5.8 Mix_HookMusic
        4.5.9 Mix_VolumeMusic
        4.5.10 Mix_PauseMusic
        4.5.11 Mix_ResumeMusic
        4.5.12 Mix_RewindMusic
        4.5.13 Mix_SetMusicPosition
        4.5.14 Mix_SetMusicCMD
        4.5.15 Mix_HaltMusic
        4.5.16 Mix_FadeOutMusic
        4.5.17 Mix_HookMusicFinished
        4.5.18 Mix_GetMusicType
        4.5.19 Mix_PlayingMusic
        4.5.20 Mix_PausedMusic
        4.5.21 Mix_FadingMusic
        4.5.22 Mix_GetMusicHookData
      4.6 Effects
        4.6.1 Mix_RegisterEffect
        4.6.2 Mix_UnregisterEffect
        4.6.3 Mix_UnregisterAllEffects
        4.6.4 Mix_SetPostMix
        4.6.5 Mix_SetPanning
        4.6.6 Mix_SetDistance
        4.6.7 Mix_SetPosition
        4.6.8 Mix_SetReverseStereo
    5. Types
      5.1 Mix_Chunk
      5.2 Mix_Music
      5.3 Mix_MusicType
      5.4 Mix_Fading
      5.5 Mix_EffectFunc_t
      5.6 Mix_EffectDone_t
    6. Defines
    7. Glossary
    Index
[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. Overview
2. Getting Started
3. Conflicts
4. Functions
5. Types
6. Defines
7. Glossary
Index
[Top] [Contents] [Index] [ ? ]

About this document

This document was generated on November, 13 2009 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated on November, 13 2009 using texi2html


SDL_net 1.2.7

1. Overview The README from the SDL_net distribution

2. Getting Started Using SDL_net

3. Functions | Functions supported by the SDL_net API
4. Types | Types used with the SDL_net API
5. Defines | Defined values/macros in the SDL_net API

6. Glossary Terms used in this document

Index Index of selected words
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1. Overview

A Little Bit About Me

I am currently, as I write this document, a programmer for Raytheon. There I do all sorts of communications, network, GUI, and other general programming tasks in C/C++ on the Solaris and sometimes Linux Operating Systems. I have been programming network code at work and in my free time for about 8 years. I find there is always more to learn about network coding, but the rewards for making something comunicate over what can only be called the most chaotic channel of information transfer are sometimes to much fun to ignore. I have coded only a few things in SDL_net that I would call complete projects. However SDL_net does make network coding easier and more portable than anything I could code using just plain BSD sockets. I was happy that I could finally base my code on something that is portable and small enough to be unintrusive. SDL_net does sometimes seem to oversimplify some things, but in the end I found that if I couldn't do it in SDL_net then perhaps I'm not doing something that is worthwhile. Of course I have and will continue to do things that are not so worthwhile perhaps, using SDL_net. Like a Web Server library, and an IRC client library. But I still enjoy making them anyway! So if you are making a game, or doing a school project, or even making a no-fun application, SDL_net is a viable choice in my opinion for almost any of these tasks. If you are interested in multicast and non-TCP/IPv4 networking then SDL_net is not the right thing for you. Everyone else, please make more network games that are fun to play, and portable enough that more people are out there to play with. I, meanwhile, will continue writting documentation and applications and games that will likely become vapourware before they even see the light of day, but I'll be having fun the whole time.

Feel free to contact me: JonathanCAtkins@gmail.com

I am also usually on IRC at irc.freenode.net in the #SDL channel as LIM

This is the README in the SDL_net source archive.

SDL_net 1.2

The latest version of this library is available from:
SDL_net Homepage

This is an example portable network library for use with SDL. It is available under the GNU Library General Public License. The API can be found in the file SDL_net.h This library supports UNIX, Windows, and BeOS. MacOS support is being written.

The demo program is a chat client and server. The chat client requires the sample GUI library available at:
GUIlib Homepage
The chat client connects to the server via TCP, registering itself. The server sends back a list of connected clients, and keeps the client updated with the status of other clients. Every line of text from a client is sent via UDP to every other client.

Note that this isn't necessarily how you would want to write a chat program, but it demonstrates how to use the basic features of the network library.

Enjoy!

-Sam Lantinga and Roy Wood

You may want to look at
Beej's Guide to Network Programming, which explains network programming using BSD sockets. You can apply the knowledge from there while using SDL_net.

And here's a bit of humor for you to look at as you deal with networking terms.

Dr. Suess as a Network Wizard

Gene_Ziegler@Cornell.edu

Here's an easy game to play.
Here's an easy thing to say....

If a packet hits a pocket on a socket on a port,
and the bus is interupted as a very last resort,
and the address of the memory makes your floppy disk abort
then the socket packet pocket has an error to report!

If your cursor finds a menu item followed by a dash,
and the double-clicking icon puts your window in the trash,
and your data is corrupted cause the index doesn't hash,
then your situation's hopeless, and your system's gona crash.

You can't say this? What a shame, sir!
We'll find you another game, sir.

If the label on the cable on the table at your house
says the network is connected to the button on your mouse,
but your packets want to tunnel on another protocol,
that's repeatedly rejected by the printer down the hall,
and your screen is all distorted by the side-effects of gauss,
so your icons in the window are as wavy as a souse,
then you may as well reboot and go out with a bang,
cause as sure as I'm a poet, the sucker's gunna hang!

When the copy of your floppy's getting sloppy on the disk,
and the microcode instructions cause unecessary risc,
then you have to flash your memory and you'll want to RAM your ROM.
quickly turn of your computer and be sure to tell your mom!

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2. Getting Started

This assumes you have gotten SDL_net and installed it on your system. SDL_net has an INSTALL document in the source distribution to help you get it compiled and installed.

Generally, installation consists of:

./configure
make
make install

You may also want to look at some demonstration code which may be downloaded from:
http://www.jonatkins.org/SDL_net/

2.1 Includes | The include files to use for SDL_net
2.2 Compiling | Using the SDL_net library and header file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.1 Includes

To use SDL_net functions in a C/C++ source code file, you must use the SDL_net.h include file:

#include "SDL_net.h"

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2 Compiling

To link with SDL_net you should use sdl-config to get the required SDL compilation options. After that, compiling with SDL_net is quite easy.
Note: Some systems may not have the SDL_net library and include file in the same place as the SDL library and includes are located, in that case you will need to add more -I and -L paths to these command lines.

Simple Example for compiling an object file:

cc -c `sdl-config --cflags` mysource.c

Simple Example for compiling an object file:

cc -o myprogram mysource.o `sdl-config --libs` -lSDL_net

Now myprogram is ready to run.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3. Functions

These are the functions in the SDL_net API.

3.1 General | API activation, versioning, and byte order helpers
3.2 Name Resolution | Hostname and numeric IP lookup (IPaddress functions)
3.3 TCP Sockets | Working with TCP connections
3.4 UDP Sockets | Working with UDP semi-connections
3.5 UDP Packets | Working with the UDPpacket type
3.6 Socket Sets | Working on demand with sockets
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1 General

The basic API startup, cleanup and versioning methods, along with a few network byte order data helpers.

Info
3.1.1 SDLNet_Linked_Version Get version number
Activation
3.1.2 SDLNet_Init | Start up SDL_net functionality
3.1.3 SDLNet_Quit | Stop SDL_net functionality
Errors
3.1.4 SDLNet_GetError Get the current error string
Data Byte Order Helpers
3.1.5 SDLNet_Write16 | Put a 16bit number in network ordered data
3.1.6 SDLNet_Write32 | Put a 32bit number in network ordered data
3.1.7 SDLNet_Read16 | Get a 16bit number from network ordered data
3.1.8 SDLNet_Read32 | Get a 32bit number from network ordered data

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.1 SDLNet_Linked_Version

const SDL_version *SDLNet_Linked_Version()
void SDL_NET_VERSION(SDL_version *compile_version)

This works similar to SDL_Linked_Version and SDL_VERSION.
Using these you can compare the runtime version to the version that you compiled with.
No prior library initialization is needed to call these functions/macros.

SDL_version compile_version;
const SDL_version *link_version=SDLNet_Linked_Version();
SDL_NET_VERSION(&compile_version);
printf("compiled with SDL_net version: %d.%d.%d\n",
        compile_version.major,
        compile_version.minor,
        compile_version.patch);
printf("running with SDL_net version: %d.%d.%d\n",
        link_version->major,
        link_version->minor,
        link_version->patch);

See Also:
3.1.2 SDLNet_Init

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.2 SDLNet_Init

int SDLNet_Init()

Initialize the network API.
This must be called before using other functions in this library.
SDL must be initialized before this call.

Returns: 0 on success, -1 on errors

if(SDL_Init(0)==-1) {
    printf("SDL_Init: %s\n", SDL_GetError());
    exit(1);
}
if(SDLNet_Init()==-1) {
    printf("SDLNet_Init: %s\n", SDLNet_GetError());
    exit(2);
}

See Also:
3.1.3 SDLNet_Quit

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.3 SDLNet_Quit

void SDLNet_Quit()

Shutdown and cleanup the network API.
After calling this all sockets are closed, and the SDL_net functions should not be used. You may, of course, use SDLNet_Init to use the functionality again.

SDLNet_Quit();
// you could SDL_Quit(); here...or not.

See Also:
3.1.2 SDLNet_Init

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.4 SDLNet_GetError

char *SDLNet_GetError()

This is the same as SDL_GetError, which returns the last error set as a string which you may use to tell the user what happened when an error status has been returned from an SDLNet_function.

Returns: a char pointer (string) containing a humam readble version or the reason for the last error that occured.

printf("Oh My Goodness, an error : %s", SDLNet_GetError());

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.5 SDLNet_Write16

void SDLNet_Write16(Uint16 value, void *area)

value
The 16bit number to put into the area buffer
area
The pointer into a data buffer, at which to put the number

Put the 16bit (a short on 32bit systems) value into the data buffer area in network byte order. This helps avoid byte order differences between two systems that are talking over the network. The value can be a signed number, the unsigned parameter type doesn't affect the data. The area pointer need not be at the beginning of a buffer, but must have at least 2 bytes of space left, including the byte currently pointed at.

// put my number into a data buffer to prepare for sending to a remote host
char data[1024];
Sint16 number=12345;
SDLNet_Write16((Uint16)number,data);

See Also:
3.1.7 SDLNet_Read16, 3.1.6 SDLNet_Write32

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.6 SDLNet_Write32

void SDLNet_Write32(Uint32 value, void *area)

value
The 32bit number to put into the area buffer
area
The pointer into a data buffer, at which to put the number

Put the 32bit (a long on 32bit systems) value into the data buffer area in network byte order. This helps avoid byte order differences between two systems that are talking over the network. The value can be a signed number, the unsigned parameter type doesn't affect the data. The area pointer need not be at the beginning of a buffer, but must have at least 4 bytes of space left, including the byte currently pointed at.

// put my number into a data buffer to prepare for sending to a remote host
char data[1024];
Uint32 number=0xDEADBEEF;
SDLNet_Write32(number,data);

See Also:
3.1.8 SDLNet_Read32, 3.1.5 SDLNet_Write16

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.7 SDLNet_Read16

Uint16 SDLNet_Read16(void *area)

area
The pointer into a data buffer, at which to get the number from

Get a 16bit (a short on 32bit systems) value from the data buffer area which is in network byte order. This helps avoid byte order differences between two systems that are talking over the network. The returned value can be a signed number, the unsigned parameter type doesn't affect the data. The area pointer need not be at the beginning of a buffer, but must have at least 2 bytes of space left, including the byte currently pointed at.

// get a number from a data buffer to use on this host
//char *ptr; //this points into a previously received data buffer
Sint16 number;
number=(Sint16) SDLNet_Read16(ptr);
// number is now in your hosts byte order, ready to use.

See Also:
3.1.5 SDLNet_Write16, 3.1.8 SDLNet_Read32

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.8 SDLNet_Read32

Uint32 SDLNet_Read32(void *area)

area
The pointer into a data buffer, at which to get the number from

Get a 32bit (a long on 32bit systems) value from the data buffer area which is in network byte order. This helps avoid byte order differences between two systems that are talking over the network. The returned value can be a signed number, the unsigned parameter type doesn't affect the data. The area pointer need not be at the beginning of a buffer, but must have at least 4 bytes of space left, including the byte currently pointed at.

// get a number from a data buffer to use on this host
//char *ptr; //this points into a previously received data buffer
Uint32 number;
number=SDLNet_Read32(ptr);
// number is now in your hosts byte order, ready to use.

See Also:
3.1.6 SDLNet_Write32, 3.1.7 SDLNet_Read16

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2 Name Resolution

These functions are used to resolve hostnames and numerical IPv4 Address to each other.

3.2.1 SDLNet_ResolveHost
3.2.2 SDLNet_ResolveIP

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.1 SDLNet_ResolveHost

int SDLNet_ResolveHost(IPaddress *address, const char *host, Uint16 port)

address
This points to the IPaddress that will be filled in. It doesn't need to be set before calling this, but it must be allocated in memory.
host
For connecting to a server, this is the hostname or IP in a string.
For becoming a server, this is NULL. If you do use NULL, all network interfaces would be listened to for incoming connections, using the INADDR_ANY address.
port
For connecting to a server, this is the the servers listening port number.
For becoming a server, this is the port to listen on.
If you are just doing Domain Name Resolution functions, this can be 0.

Resolve the string host, and fill in the IPaddress pointed to by address with the resolved IP and the port number passed in through port.
This is the best way to fill in the IPaddress struct for later use. This function does not actually open any sockets, it is used to prepare the arguments for the socket opening functions.
WARNING: this function will put the host and port into Network Byte Order into the address fields, so make sure you pass in the data in your hosts byte order. (normally not an issue)

Returns: 0 on success. -1 on errors, plus address.host will be INADDR_NONE. An error would likely be that the address could not be resolved.

For a server listening on all interfaces, on port 1234:

// create a server type IPaddress on port 1234
IPaddress ipaddress;
SDLNet_ResolveHost(&ipaddress, NULL, 1234);

For a client connecting to "host.domain.ext", at port 1234:

// create an IPaddress for host name "host.domain.ext" on port 1234
// this is used by a client
IPaddress ipaddress;
SDLNet_ResolveHost(&ipaddress, "host.domain.ext", 1234);

See Also:
3.2.2 SDLNet_ResolveIP, 4.1 IPaddress

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.2 SDLNet_ResolveIP

const char *SDLNet_ResolveIP(IPaddress *address)

address
This points to the IPaddress that will be resolved to a host name. The address->port is ignored.

Resolve the IPv4 numeric address in address->host, and return the hostname as a string.

Returns: a valid char pointer (string) on success. the returned hostname will have host and domain, as in "host.domain.ext". NULL is returned on errors, such as when it's not able to resolve the host name. The returned pointer is not to be freed. Each time you call this function the previous pointer's data will change to the new value, so you may have to copy it into a local buffer to keep it around longer.

// resolve the host name of the address in ipaddress
//IPaddress ipaddress;
char *host;
if(!(host=SDLNet_ResolveIP(&ipaddress))) {
    printf("SDLNet_ResolveIP: %s\n", SDLNet_GetError());
    exit(1);
}

See Also:
3.2.1 SDLNet_ResolveHost, 4.1 IPaddress

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3 TCP Sockets

These functions are used to work with TCP Sockets. TCP is used with a full connection, whereas UDP is connectionless. TCP also ensures that all packets reach the destionation (when possible). TCP also ensures that packets are received in the same order as sent.

General
3.3.1 SDLNet_TCP_Open | Open a TCP client or server socket
3.3.2 SDLNet_TCP_Close | Close a TCP socket
Server
3.3.3 SDLNet_TCP_Accept Accept a connection on a server socket
Information
3.3.4 SDLNet_TCP_GetPeerAddress Get the remote host address and port number
Input/Output
3.3.5 SDLNet_TCP_Send | Send data over a connected socket
3.3.6 SDLNet_TCP_Recv | Receive data from a connected socket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.1 SDLNet_TCP_Open

TCPsocket SDLNet_TCP_Open(IPaddress *ip)

ip
This points to the IPaddress that contains the resolved IP address and port number to use.

Connect to the host and port contained in ip using a TCP connection.
If the host is INADDR_ANY, then only the port number is used, and a socket is created that can be used to later accept incoming TCP connections.

Returns: a valid TCPsocket on success, which indicates a successful connection has been established, or a socket has been created that is valid to accept incoming TCP connections. NULL is returned on errors, such as when it's not able to create a socket, or it cannot connect to host and/or port contained in ip.

// connect to localhost at port 9999 using TCP (client)
IPaddress ip;
TCPsocket tcpsock;

if(SDLNet_ResolveHost(&ip,"localhost",9999)==-1) {
    printf("SDLNet_ResolveHost: %s\n", SDLNet_GetError());
    exit(1);
}

tcpsock=SDLNet_TCP_Open(&ip);
if(!tcpsock) {
    printf("SDLNet_TCP_Open: %s\n", SDLNet_GetError());
    exit(2);
}

// create a listening TCP socket on port 9999 (server)
IPaddress ip;
TCPsocket tcpsock;

if(SDLNet_ResolveHost(&ip,NULL,9999)==-1) {
    printf("SDLNet_ResolveHost: %s\n", SDLNet_GetError());
    exit(1);
}

tcpsock=SDLNet_TCP_Open(&ip);
if(!tcpsock) {
    printf("SDLNet_TCP_Open: %s\n", SDLNet_GetError());
    exit(2);
}

See Also:
3.3.3 SDLNet_TCP_Accept, 3.3.2 SDLNet_TCP_Close, 4.1 IPaddress, 4.2 TCPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.2 SDLNet_TCP_Close

void SDLNet_TCP_Close(TCPsocket sock)

sock
A valid TCPsocket. This can be a server or client type socket.

This shutsdown, disconnects, and closes the TCPsocket sock.
After this, you can be assured that this socket is not in use anymore. You can reuse the sock variable after this to open a new connection with SDLNet_TCP_Open. Do not try to use any other functions on a closed socket, as it is now invalid.

Returns: nothing, this always succeeds for all we need to know.

// close the connection on sock
//TCPsocket sock;

SDLNet_TCP_Close(sock);

See Also:
3.3.1 SDLNet_TCP_Open, 4.2 TCPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.3 SDLNet_TCP_Accept

TCPsocket SDLNet_TCP_Accept(TCPsocket server)

server
This is the server TCPsocket which was previously created by
SDLNet_TCP_Open.

Accept an incoming connection on the server TCPsocket.
Do not use this function on a connected socket. Server sockets are never connected to a remote host. What you get back is a new TCPsocket that is connected to the remote host.
This is a non-blocking call, so if no connections are there to be accepted, you will get a NULL TCPsocket and the program will continue going.

Returns: a valid TCPsocket on success, which indicates a successful connection has been established. NULL is returned on errors, such as when it's not able to create a socket, or it cannot finish connecting to the originating host and port. There also may not be a connection attempt in progress, so of course you cannot accept nothing, and you get a NULL in this case as well.

// accept a connection coming in on server_tcpsock
TCPsocket new_tcpsock;

new_tcpsock=SDLNet_TCP_Accept(server_tcpsock);
if(!new_tcpsock) {
    printf("SDLNet_TCP_Accept: %s\n", SDLNet_GetError());
}
else {
    // communicate over new_tcpsock
}

See Also:
3.3.1 SDLNet_TCP_Open, 3.3.4 SDLNet_TCP_GetPeerAddress, 3.3.2 SDLNet_TCP_Close, 4.2 TCPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.4 SDLNet_TCP_GetPeerAddress

IPaddress *SDLNet_TCP_GetPeerAddress(TCPsocket sock)

sock
This is a valid TCPsocket.

Get the Peer's (the other side of the connection, the remote side, not the local side) IP address and port number.

Returns: an IPaddress. NULL is returned on errors, or when sock is a server socket.

// get the remote IP and port
//TCPsocket new_tcpsock;
IPaddress *remote_ip;

remote_ip=SDLNet_TCP_GetPeerAddress(new_tcpsock);
if(!remote_ip) {
    printf("SDLNet_TCP_GetPeerAddress: %s\n", SDLNet_GetError());
    printf("This may be a server socket.\n");
}
else {
    // print the info in IPaddress or something else...
}

See Also:
3.3.1 SDLNet_TCP_Open, 3.3.3 SDLNet_TCP_Accept, 4.1 IPaddress, 4.2 TCPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.5 SDLNet_TCP_Send

int SDLNet_TCP_Send(TCPsocket sock, const void *data, int len)

sock
This is a valid, connected, TCPsocket.
data
This is a pointer to the data to send over sock.
len
This is the length (in bytes) if the data.

Send data of length len over the socket sock.
This routine is not used for server sockets.

Returns: the number of bytes sent. If the number returned is less than len, then an error occured, such as the client disconnecting.

// send a hello over sock
//TCPsocket sock;
int len,result;
char *msg="Hello!";

len=strlen(msg)+1; // add one for the terminating NULL
result=SDLNet_TCP_Send(sock,msg,len);
if(result<len) {
    printf("SDLNet_TCP_Send: %s\n", SDLNet_GetError());
    // It may be good to disconnect sock because it is likely invalid now.
}

See Also:
3.3.6 SDLNet_TCP_Recv, 3.3.3 SDLNet_TCP_Accept, 3.3.1 SDLNet_TCP_Open, 3.3.4 SDLNet_TCP_GetPeerAddress, 3.3.2 SDLNet_TCP_Close, 4.2 TCPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.6 SDLNet_TCP_Recv

int SDLNet_TCP_Recv(TCPsocket sock, void *data, int maxlen)

sock
This is a valid, connected, TCPsocket.
data
This is a pointer to the buffer that receives the data from sock.
maxlen
This is the maximum length (in bytes) that will be read into data.

Receive data of exactly length maxlen bytes from the socket sock, into the memory pointed to by data.
This routine is not used for server sockets.
Unless there is an error, or the connection is closed, the buffer will read maxlen bytes. If you read more than is sent from the other end, then it will wait until the full requested length is sent, or until the connection is closed from the other end.
You may have to read 1 byte at a time for some applications, for instance, text applications where blocks of text are sent, but you want to read line by line. In that case you may want to find the newline characters yourself to break the lines up, instead of reading some inordinate amount of text which may contain many lines, or not even a full line of text.

Returns: the number of bytes received. If the number returned is less than or equal to zero, then an error occured, or the remote host has closed the connection.

// receive some text from sock
//TCPsocket sock;
#define MAXLEN 1024
int result;
char msg[MAXLEN];

result=SDLNet_TCP_Recv(sock,msg,MAXLEN);
if(result<=0) {
    // An error may have occured, but sometimes you can just ignore it
    // It may be good to disconnect sock because it is likely invalid now.
}
printf("Received: \"%s\"\n",msg);

See Also:
3.3.5 SDLNet_TCP_Send, 3.3.3 SDLNet_TCP_Accept, 3.3.1 SDLNet_TCP_Open, 3.3.4 SDLNet_TCP_GetPeerAddress, 3.3.2 SDLNet_TCP_Close, 4.2 TCPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4 UDP Sockets

These functions are used to work with UDP Sockets.
UDP is connectionless, but can be used as if it is connected, in the sense that you don't have to address every outgoing packet if you don't want to. This is done by binding a socket to remote IP address and port pairs.
UDP has no delivery guarantees, each packet has a chance of never getting to the destination.
UDP packets may also be received completely out of order, as compared to the order of sending them.
All these seeming bad qualities are made up for in speed. UDP is faster than TCP, and so many games and speed sensitive applications, which may also be sending redundant data anyways, such as a game state, prefer to use UDP for the speed benefits.

SDL_net has a concept of channels, which help you to matchup packets to specific clients easier. These channel numbers are not transmitted in the UDP packet data, but rather when a UDP socket receives or sends packets, a channel number may be used instead of an IPaddress to refer to the source or destination. You might prefer not to use channels at all, which is fine. SDL_net provides them only as an optional convenience.

General
3.4.1 SDLNet_UDP_Open | Create a UDP socket
3.4.2 SDLNet_UDP_Close | Close and free a UDP socket
Channel Binding
3.4.3 SDLNet_UDP_Bind | Assign an IP address number to a socket channel
3.4.4 SDLNet_UDP_Unbind | Remove all assigned IP addresses from a socket channel
3.4.5 SDLNet_UDP_GetPeerAddress | Get the assigned IP address for a socket channel or get the port you opened the socket with
Single UDPpacket
3.4.6 SDLNet_UDP_Send | Send a UDPpacket
3.4.7 SDLNet_UDP_Recv | Receive into a UDPpacket
Many UDPpackets in a vector (array)
3.4.8 SDLNet_UDP_SendV | Send a UDPpacket vector
3.4.9 SDLNet_UDP_RecvV | Receive into a UDPpacket vector

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.1 SDLNet_UDP_Open

UDPsocket SDLNet_UDP_Open(Uint16 port)

port
This is the port number (in native byte order) on which to receive UDP packets. Most servers will want to use a known port number here so that clients can easily communicate with the server. This can also be zero, which then opens an anonymous unused port number, to most likely be used to send UDP packets from.

Open a socket to be used for UDP packet sending and/or receiving.
If a non-zero port is given it will be used, otherwise any open port number will be used automatically.
Unlike TCP sockets, this socket does not require a remote host IP to connect to, this is because UDP ports are never actually connected like TCP ports are.
This socket is able to send and receive directly after this simple creation.

Returns: a valid UDPsocket on success. NULL is returned on errors, such as when it's not able to create a socket, or it cannot assign the non-zero port as requested.

Note that below I say server, but clients may also open a specific port, though it is prefered that a client be more flexible, given that the port may be already allocated by another process, such as a server. In such a case you will not be able to open the socket, and your program will be stuck, so it is better to just use whatever port you are given by using a specified port of zero. Then the client will always work. The client can inform the server what port to talk back to, or the server can just look at the source of the packets it is receiving to know where to respond to.

// create a UDPsocket on port 6666 (server)
UDPsocket udpsock;

udpsock=SDLNet_UDP_Open(6666);
if(!udpsock) {
    printf("SDLNet_UDP_Open: %s\n", SDLNet_GetError());
    exit(2);
}

// create a UDPsocket on any available port (client)
UDPsocket udpsock;

udpsock=SDLNet_UDP_Open(0);
if(!udpsock) {
    printf("SDLNet_UDP_Open: %s\n", SDLNet_GetError());
    exit(2);
}

See Also:
3.4.2 SDLNet_UDP_Close, 4.3 UDPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.2 SDLNet_UDP_Close

void SDLNet_UDP_Close(UDPsocket sock)

sock
A valid UDPsocket to shutdown, close, and free.

Shutdown, close, and free a UDPsocket.
Don't use the UDPsocket after calling this, except to open a new one.

Returns: nothing, this always succeeds.

// unbind all addresses on the UDPsocket channel 0
//UDPsocket udpsock;

SDLNet_UDP_Close(udpsock);
udpsock=NULL; //this helps us know that this UDPsocket is not valid anymore

See Also:
3.4.1 SDLNet_UDP_Open, 4.3 UDPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.3 SDLNet_UDP_Bind

int SDLNet_UDP_Bind(UDPsocket sock, int channel, IPaddress *address)

sock
the UDPsocket on which to assign the address.
channel
The channel to assign address to. This should be less than
SDLNET_MAX_UDPCHANNELS. If -1 is used, then the first unbound channel will be used, this should only be used for incomming packet filtering, as it will find the first channel with less than SDLNET_MAX_UDPADDRESSES assigned to it and use that one.
address
The resolved IPaddress to assign to the socket's channel. The host and port are both used.
It is not helpful to bind 0.0.0.0 to a channel.

Bind an address to a channel on a socket.
Incoming packets are only allowed from bound addresses for the socket channel.
All outgoing packets on that channel, regardless of the packets internal address, will attempt to send once on each bound address on that channel.
You may assign up to SDLNET_MAX_UDPADDRESSES to each channel.

Returns: The channel number that was bound. -1 is returned on errors, such as no free channels, or this channel has SDLNET_MAX_UDPADDRESSES already assigned to it, or you have used a channel higher or equal to SDLNET_MAX_UDPCHANNELS, or lower than -1.

// Bind address to the first free channel
//UDPsocket udpsock;
//IPaddress *address;
int channel;

channel=SDLNet_UDP_Bind(udpsock, -1, address);
if(channel==-1) {
    printf("SDLNet_UDP_Bind: %s\n", SDLNet_GetError());
    // do something because we failed to bind
}

See Also:
3.4.4 SDLNet_UDP_Unbind, 3.4.5 SDLNet_UDP_GetPeerAddress, 3.4.1 SDLNet_UDP_Open, 4.1 IPaddress, 4.3 UDPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.4 SDLNet_UDP_Unbind

void SDLNet_UDP_Unbind(UDPsocket sock, int channel)

sock
A valid UDPsocket to unbind addresses from.
channel
The channel to unbind the addresses from in the UDPsocket.

This removes all previously assigned (bound) addresses from a socket channel.
After this you may bind new addresses to the socket channel.

Returns: nothing, this always succeeds.

// unbind all addresses on the UDPsocket channel 0
//UDPsocket udpsock;

SDLNet_UDP_Unbind(udpsock, 0);

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.2 SDLNet_UDP_Close, 4.3 UDPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.5 SDLNet_UDP_GetPeerAddress

IPaddress *SDLNet_UDP_GetPeerAddress(UDPsocket sock, int channel)

sock
A valid UDPsocket that probably has an address assigned to the channel.
channel
The channel to get the primary address from in the socket. This may also be -1 to get the port which this socket is bound to on the local computer.

Get the primary address assigned to this channel. Only the first bound address is returned.
When channel is -1, get the port that this socket is bound to on the local computer, this only means something if you opened the socket with a specific port number.
Do not free the returned IPaddress pointer.

Returns: a pointer to an IPaddress. NULL is returned for unbound channels and on any errors.

// get the primary address bound to UDPsocket channel 0
//UDPsocket udpsock;
IPaddress *address;

address=SDLNet_UDP_GetPeerAddress(udpsock, 0);
if(!address) {
    printf("SDLNet_UDP_GetPeerAddress: %s\n", SDLNet_GetError());
    // do something because we failed to get the address
}
else {
    // perhaps print out address->host and address->port
}

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.4 SDLNet_UDP_Unbind, 4.1 IPaddress, 4.3 UDPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.6 SDLNet_UDP_Send

int SDLNet_UDP_Send(UDPsocket sock, int channel, UDPpacket *packet)

sock
A valid UDPsocket.
channel
what channel to send packet on.
packet
The packet to send.

Send packet using the specified socket sock, use ing the specified channel or else the packet's address.
If channel is not -1 then the packet is sent to all the socket channels bound addresses. If socket sock's channel is not bound to any destinations, then the packet is not sent at all!
If the channel is -1, then the packet's address is used as the destination.
Don't forget to set the length of the packet in the len element of the packet you are sending! Note: the packet->channel will be set to the channel passed in to this function. Note: The maximum size of the packet is limited by the MTU (Maximum Transfer Unit) of the transport medium. It can be as low as 250 bytes for some PPP links, and as high as 1500 bytes for ethernet. Beyond that limit the packet will fragment, and make delivery more and more unreliable as lost fragments cause the whole packet to be discarded.

Returns: The number of destinations sent to that worked. 0 is returned on errors.
Note that since a channel can point to multiple destinations, there should be just as many packets sent, so dont assume it will always return 1 on success. Unfortunately there's no way to get the number of destinations bound to a channel, so either you have to remember the number bound, or just test for the zero return value indicating all channels failed.

// send a packet using a UDPsocket, using the packet's channel as the channel
//UDPsocket udpsock;
//UDPpacket *packet;
int numsent;

numsent=SDLNet_UDP_Send(udpsock, packet->channel, packet);
if(!numsent) {
    printf("SDLNet_UDP_Send: %s\n", SDLNet_GetError());
    // do something because we failed to send
    // this may just be because no addresses are bound to the channel...
}

Here's a way of sending one packet using it's internal channel setting.
This is actually what SDLNet_UDP_Send ends up calling for you.

// send a packet using a UDPsocket, using the packet's channel as the channel
//UDPsocket udpsock;
//UDPpacket *packet;
int numsent;

numsent=SDLNet_UDP_SendV(sock, &packet, 1);
if(!numsent) {
    printf("SDLNet_UDP_SendV: %s\n", SDLNet_GetError());
    // do something because we failed to send
    // this may just be because no addresses are bound to the channel...
}

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.8 SDLNet_UDP_SendV, 3.4.7 SDLNet_UDP_Recv, 3.4.9 SDLNet_UDP_RecvV, 4.4 UDPpacket, 4.3 UDPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.7 SDLNet_UDP_Recv

int SDLNet_UDP_Recv(UDPsocket sock, UDPpacket *packet)

sock
A valid UDPsocket.
packet
The packet to receive into.

Receive a packet on the specified sock socket.
The packet you pass in must have enough of a data size allocated for the incoming packet data to fit into. This means you should have knowledge of your size needs before trying to receive UDP packets.
The packet will have it's address set to the remote sender's address.
The socket's channels are checked in highest to lowest order, so if an address is bound to multiple channels, the highest channel with the source address bound will be retreived before the lower bound channels. So, the packets channel will also be set to the highest numbered channel that has the remote address and port assigned to it. Otherwise the channel will -1, which you can filter out easily if you want to ignore unbound source address.
Note that the local and remote channel numbers do not have to, and probably won't, match, as they are only local settings, they are not sent in the packet.
This is a non-blocking call, meaning if there's no data ready to be received the function will return.

Returns: 1 is returned when a packet is received. 0 is returned when no packets are received. -1 is returned on errors.

// try to receive a waiting udp packet
//UDPsocket udpsock;
UDPpacket packet;
int numrecv;

numrecv=SDLNet_UDP_Recv(udpsock, &packet);
if(numrecv) {
    // do something with packet
}

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.6 SDLNet_UDP_Send, 3.4.8 SDLNet_UDP_SendV, 3.4.9 SDLNet_UDP_RecvV, 4.4 UDPpacket, 4.3 UDPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.8 SDLNet_UDP_SendV

int SDLNet_UDP_SendV(UDPsocket sock, UDPpacket **packetV, int npackets)

sock
A valid UDPsocket.
packetV
The vector of packets to send.
npackets
number of packets in the packetV vector to send.

Send npackets of packetV using the specified sock socket.
Each packet is sent in the same way as in SDLNet_UDP_Send (see section 3.4.6 SDLNet_UDP_Send).
Don't forget to set the length of the packets in the len element of the packets you are sending!

Returns: The number of destinations sent to that worked, for each packet in the vector, all summed up. 0 is returned on errors.

// send a vector of 10 packets using UDPsocket
//UDPsocket udpsock;
//UDPpacket **packetV;
int numsent;

numsent=SDLNet_UDP_SendV(udpsock, packetV, 10);
if(!numsent) {
    printf("SDLNet_UDP_SendV: %s\n", SDLNet_GetError());
    // do something because we failed to send
    // this may just be because no addresses are bound to the channels...
}

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.6 SDLNet_UDP_Send, 3.4.7 SDLNet_UDP_Recv, 3.4.9 SDLNet_UDP_RecvV, 4.4 UDPpacket, 4.3 UDPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.9 SDLNet_UDP_RecvV

int SDLNet_UDP_RecvV(UDPsocket sock, UDPpacket **packetV)

sock
A valid UDPsocket.
packet
The packet to receive into.

Receive into a packet vector on the specified socket sock.
packetV is a NULL terminated array. Packets will be received until the NULL is reached, or there are none ready to be received.
This call is otherwise the same as SDLNet_UDP_Recv (see section 3.4.7 SDLNet_UDP_Recv).

Returns: the number of packets received. 0 is returned when no packets are received. -1 is returned on errors.

// try to receive some waiting udp packets
//UDPsocket udpsock;
//UDPpacket **packetV;
int numrecv, i;

numrecv=SDLNet_UDP_RecvV(udpsock, &packetV);
if(numrecv==-1) {
    // handle error, perhaps just print out the SDL_GetError string.
}
for(i=0; i<numrecv; i++) {
    // do something with packetV[i]
}

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.6 SDLNet_UDP_Send, 3.4.8 SDLNet_UDP_SendV, 3.4.7 SDLNet_UDP_Recv, 4.4 UDPpacket, 4.3 UDPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5 UDP Packets

These functions are used to work with the UDPpacket type. This type is used with UDP sockets to transmit and receive data.

Single UDPpacket
3.5.1 SDLNet_AllocPacket | Allocate a new UDP packet with a data buffer
3.5.2 SDLNet_ResizePacket | Resize the data buffer in a UDPpacket
3.5.3 SDLNet_FreePacket | Free a previously allocated UDPpacket
Many UDPpackets in a vector (array)
3.5.4 SDLNet_AllocPacketV | Allocate a vector of UDPpackets
3.5.5 SDLNet_FreePacketV | Free a vector of UDPpackets

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.1 SDLNet_AllocPacket

UDPpacket *SDLNet_AllocPacket(int size)

size
Size, in bytes, of the data buffer to be allocated in the new UDPpacket.
Zero is invalid.

Create (via malloc) a new UDPpacket with a data buffer of size bytes.
The new packet should be freed using SDLNet_FreePacket when you are done using it.

Returns: a pointer to a new empty UDPpacket. NULL is returned on errors, such as out-of-memory.

// create a new UDPpacket to hold 1024 bytes of data
UDPpacket *packet;

packet=SDLNet_AllocPacket(1024);
if(!packet) {
    printf("SDLNet_AllocPacket: %s\n", SDLNet_GetError());
    // perhaps do something else since you can't make this packet
}
else {
    // do stuff with this new packet
    // SDLNet_FreePacket this packet when finished with it
}

See Also:
3.5.4 SDLNet_AllocPacketV, 3.5.2 SDLNet_ResizePacket, 3.5.3 SDLNet_FreePacket, 3.4.6 SDLNet_UDP_Send, 3.4.8 SDLNet_UDP_SendV, 4.4 UDPpacket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.2 SDLNet_ResizePacket

int SDLNet_ResizePacket(UDPpacket *packet, int size)

packet
A pointer to the UDPpacket to be resized.
size
The new desired size, in bytes, of the data buffer to be allocated in the UDPpacket.
Zero is invalid.

Resize a UDPpackets data buffer to size bytes. The old data buffer will not be retained, so the new buffer is invalid after this call.

Returns: the new size of the data in the packet. If the number returned is less than what you asked for, that's an error.

// Resize a UDPpacket to hold 2048 bytes of data
//UDPpacket *packet;
int newsize;

newsize=SDLNet_ResizePacket(packet, 2048);
if(newsize<2048) {
    printf("SDLNet_ResizePacket: %s\n", SDLNet_GetError());
    // perhaps do something else since you didn't get the buffer you wanted
}
else {
    // do stuff with the resized packet
}

See Also:
3.5.1 SDLNet_AllocPacket, 3.5.4 SDLNet_AllocPacketV, 3.5.3 SDLNet_FreePacket, 4.4 UDPpacket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.3 SDLNet_FreePacket

void SDLNet_FreePacket(UDPpacket *packet)

packet
A pointer to the UDPpacket to be freed from memory.

Free a UDPpacket from memory. Do not use this UDPpacket after this function is called on it.

Returns: nothing, this always succeeds.

// Free a UDPpacket
//UDPpacket *packet;

SDLNet_FreePacket(packet);
packet=NULL; //just to help you know that it is freed

See Also:
3.5.1 SDLNet_AllocPacket, 3.5.4 SDLNet_AllocPacketV, 3.5.5 SDLNet_FreePacketV, 3.5.2 SDLNet_ResizePacket, 4.4 UDPpacket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.4 SDLNet_AllocPacketV

UDPpacket **SDLNet_AllocPacketV(int howmany, int size)

howmany
The number of UDPpackets to allocate.
size
Size, in bytes, of the data buffers to be allocated in the new UDPpackets.
Zero is invalid.

Create (via malloc) a vector of new UDPpackets, each with data buffers of size bytes. The new packet vector should be freed using SDLNet_FreePacketV when you are done using it. The returned vector is one entry longer than requested, for a terminating NULL.

Returns: a pointer to a new empty UDPpacket vector. NULL is returned on errors, such as out-of-memory.

// create a new UDPpacket vector to hold 1024 bytes of data in 10 packets
UDPpacket **packetV;

packetV=SDLNet_AllocPacketV(10, 1024);
if(!packetV) {
    printf("SDLNet_AllocPacketV: %s\n", SDLNet_GetError());
    // perhaps do something else since you can't make this packet
}
else {
    // do stuff with this new packet vector
    // SDLNet_FreePacketV this packet vector when finished with it
}

See Also:
3.5.1 SDLNet_AllocPacket, 3.5.3 SDLNet_FreePacket, 3.5.5 SDLNet_FreePacketV, 3.5.2 SDLNet_ResizePacket, 4.4 UDPpacket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.5.5 SDLNet_FreePacketV

void SDLNet_FreePacketV(UDPpacket **packetV)

packetV
A pointer to the UDPpacket vector to be freed from memory.

Free a UDPpacket vector from memory. Do not use this UDPpacket vector, or any UDPpacket in it, after this function is called on it.

Returns: nothing, this always succeeds.

// Free a UDPpacket vector
//UDPpacket **packetV;

SDLNet_FreePacketV(packetV);
packetV=NULL; //just to help you know that it is freed

See Also:
3.5.4 SDLNet_AllocPacketV, 3.5.1 SDLNet_AllocPacket, 3.5.3 SDLNet_FreePacket, 3.5.2 SDLNet_ResizePacket, 4.4 UDPpacket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6 Socket Sets

These functions are used to work with multiple sockets. They allow you to determine when a socket has data or a connection waiting to be processed. This is analogous to polling, or the select function.

General
3.6.1 SDLNet_AllocSocketSet | Create a new socket set
3.6.2 SDLNet_FreeSocketSet | Free a socket set
Setup
3.6.3 SDLNet_AddSocket | Add a socket to a socket set
3.6.4 SDLNet_DelSocket | Remove a socket from a socket set
Activity Checking
3.6.5 SDLNet_CheckSockets | Check and wait for sockets in a set to have activity
3.6.6 SDLNet_SocketReady | See if a socket has activity

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.1 SDLNet_AllocSocketSet

SDLNet_SocketSet SDLNet_AllocSocketSet(int maxsockets)

maxsockets
The maximum number of sockets you will want to watch.

Create a socket set that will be able to watch up to maxsockets number of sockets. The same socket set can be used for both UDP and TCP sockets.

Returns: A new, empty, SDLNet_SocketSet. NULL is returned on errors, such as out-of-memory.

// Create a socket set to handle up to 16 sockets
SDLNet_SocketSet set;

set=SDLNet_AllocSocketSet(16);
if(!set) {
    printf("SDLNet_AllocSocketSet: %s\n", SDLNet_GetError());
    exit(1); //most of the time this is a major error, but do what you want.
}

See Also:
3.6.2 SDLNet_FreeSocketSet, 3.6.3 SDLNet_AddSocket, 4.5 SDLNet_SocketSet, 4.3 UDPsocket, 4.2 TCPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.2 SDLNet_FreeSocketSet

void SDLNet_FreeSocketSet(SDLNet_SocketSet set)

set
The socket set to free from memory

Free the socket set from memory.
Do not reference the set after this call, except to allocate a new one.

Returns: nothing, this call always succeeds.

// free a socket set
//SDLNet_SocketSet set;

SDLNet_FreeSocketSet(set);
set=NULL; //this helps us remember that this set is not allocated

See Also:
3.6.1 SDLNet_AllocSocketSet, 3.6.3 SDLNet_AddSocket, 4.5 SDLNet_SocketSet, 4.3 UDPsocket, 4.2 TCPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.3 SDLNet_AddSocket

int SDLNet_AddSocket(SDLNet_SocketSet set, SDLNet_GenericSocket sock)
int SDLNet_TCP_AddSocket(SDLNet_SocketSet set, TCPsocket sock)
int SDLNet_UDP_AddSocket(SDLNet_SocketSet set, UDPsocket sock)

set
The socket set to add this socket to
sock
the socket to add to the socket set

Add a socket to a socket set that will be watched. TCP and UDP sockets should be added using the corrosponding macro (as in SDLNet_TCP_AddSocket for a TCP socket). The generic socket function will be called by the TCP and UDP macros. Both TCP and UDP sockets may be added to the same socket set. TCP clients and servers may all be in the same socket set. There is no limitation on the sockets in the socket set, other than they have been opened.

Returns: the number of sockets used in the set on success. -1 is returned on errors.

// add two sockets to a socket set
//SDLNet_SocketSet set;
//UDPsocket udpsock;
//TCPsocket tcpsock;
int numused;

numused=SDLNet_UDP_AddSocket(set,udpsock);
if(numused==-1) {
    printf("SDLNet_AddSocket: %s\n", SDLNet_GetError());
    // perhaps you need to restart the set and make it bigger...
}
numused=SDLNet_TCP_AddSocket(set,tcpsock);
if(numused==-1) {
    printf("SDLNet_AddSocket: %s\n", SDLNet_GetError());
    // perhaps you need to restart the set and make it bigger...
}

See Also:
3.6.1 SDLNet_AllocSocketSet, 3.6.4 SDLNet_DelSocket, 3.6.5 SDLNet_CheckSockets, 4.5 SDLNet_SocketSet, 4.3 UDPsocket, 4.2 TCPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.4 SDLNet_DelSocket

int SDLNet_DelSocket(SDLNet_SocketSet set, SDLNet_GenericSocket sock)
int SDLNet_TCP_DelSocket(SDLNet_SocketSet set, TCPsocket sock)
int SDLNet_UDP_DelSocket(SDLNet_SocketSet set, UDPsocket sock)

set
The socket set to remove this socket from
sock
the socket to remove from the socket set

Remove a socket from a socket set. Use this before closing a socket that you are watching with a socket set. This doesn't close the socket. Call the appropriate macro for TCP or UDP sockets. The generic socket function will be called by the TCP and UDP macros.

Returns: the number of sockets used in the set on success. -1 is returned on errors.

// remove two sockets from a socket set
//SDLNet_SocketSet set;
//UDPsocket udpsock;
//TCPsocket tcpsock;
int numused;

numused=SDLNet_UDP_DelSocket(set,udpsock);
if(numused==-1) {
    printf("SDLNet_DelSocket: %s\n", SDLNet_GetError());
    // perhaps the socket is not in the set
}
numused=SDLNet_TCP_DelSocket(set,tcpsock);
if(numused==-1) {
    printf("SDLNet_DelSocket: %s\n", SDLNet_GetError());
    // perhaps the socket is not in the set
}

See Also:
3.6.3 SDLNet_AddSocket, 3.6.2 SDLNet_FreeSocketSet, 4.5 SDLNet_SocketSet, 4.3 UDPsocket, 4.2 TCPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.5 SDLNet_CheckSockets

int SDLNet_CheckSockets(SDLNet_SocketSet set, Uint32 timeout)

set
The socket set to check
timeout
The amount of time (in milliseconds).
0 means no waiting.
-1 means to wait over 49 days! (think about it)

Check all sockets in the socket set for activity. If a non-zero timeout is given then this function will wait for activity, or else it will wait for timeout milliseconds.

NOTE: "activity" also includes disconnections and other errors, which would be determined by a failed read/write attempt.

Returns: the number of sockets with activity. -1 is returned on errors, and you may not get a meaningful error message. -1 is also returned for an empty set (nothing to check).

// Wait for up to 1 second for network activity
//SDLNet_SocketSet set;
int numready;

numready=SDLNet_CheckSockets(set, 1000);
if(numready==-1) {
    printf("SDLNet_CheckSockets: %s\n", SDLNet_GetError());
    //most of the time this is a system error, where perror might help you.
    perror("SDLNet_CheckSockets");
}
else if(numready) {
    printf("There are %d sockets with activity!\n",numready);
    // check all sockets with SDLNet_SocketReady and handle the active ones.
}

See Also:
3.6.6 SDLNet_SocketReady, 3.6.3 SDLNet_AddSocket, 3.6.4 SDLNet_DelSocket, 3.6.1 SDLNet_AllocSocketSet, 4.5 SDLNet_SocketSet, 4.3 UDPsocket, 4.2 TCPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.6.6 SDLNet_SocketReady

int SDLNet_SocketReady(sock)

sock
The socket to check for activity.
Both UDPsocket and TCPsocket can be used with this function.

Check whether a socket has been marked as active. This function should only be used on a socket in a socket set, and that set has to have had SDLNet_CheckSockets (see section 3.6.5 SDLNet_CheckSockets) called upon it.

Returns: non-zero for activity. zero is returned for no activity.

// Wait forever for a connection attempt
//SDLNet_SocketSet set;
//TCPsocket serversock, client;
int numready;

numready=SDLNet_CheckSockets(set, 1000);
if(numready==-1) {
    printf("SDLNet_CheckSockets: %s\n", SDLNet_GetError());
    //most of the time this is a system error, where perror might help you.
    perror("SDLNet_CheckSockets");
}
else if(numready) {
    printf("There are %d sockets with activity!\n",numready);
    // check all sockets with SDLNet_SocketReady and handle the active ones.
    if(SDLNet_SocketReady(serversock)) {
        client=SDLNet_TCP_Accept(serversock);
        if(client) {
            // play with the client.
        }
    }
}

To just quickly do network handling with no waiting, we do this.

// Check for, and handle UDP data
//SDLNet_SocketSet set;
//UDPsocket udpsock;
//UDPpacket *packet;
int numready, numpkts;

numready=SDLNet_CheckSockets(set, 0);
if(numready==-1) {
    printf("SDLNet_CheckSockets: %s\n", SDLNet_GetError());
    //most of the time this is a system error, where perror might help you.
    perror("SDLNet_CheckSockets");
}
else if(numready) {
    printf("There are %d sockets with activity!\n",numready);
    // check all sockets with SDLNet_SocketReady and handle the active ones.
    if(SDLNet_SocketReady(udpsock)) {
        numpkts=SDLNet_UDP_Recv(udpsock,&packet);
        if(numpkts) {
            // process the packet.
        }
    }
}

See Also:
3.6.5 SDLNet_CheckSockets, 3.6.3 SDLNet_AddSocket, 3.6.4 SDLNet_DelSocket, 3.6.1 SDLNet_AllocSocketSet, 4.5 SDLNet_SocketSet, 4.3 UDPsocket, 4.2 TCPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4. Types

These types are defined and used by the SDL_net API.

4.1 IPaddress | IP Address and Port number
4.2 TCPsocket | TCP socket type (opaque)
4.3 UDPsocket | UDP socket type (opaque)
4.4 UDPpacket | UDP packet data encapsulation
4.5 SDLNet_SocketSet | Socket Set type (opaque)
4.6 SDLNet_GenericSocket | A generic type for UDP and TCP sockets

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1 IPaddress

typedef struct {
    Uint32 host;            /* 32-bit IPv4 host address */
    Uint16 port;            /* 16-bit protocol port */
} IPaddress;

host
the IPv4 address of a host, encoded in Network Byte Order.
port
the IPv4 port number of a socket, encoded in Network Byte Order.

This type contains the information used to form network connections and sockets.

See Also:
3.2 Name Resolution, 3.3.1 SDLNet_TCP_Open, 4.4 UDPpacket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.2 TCPsocket

typedef struct _TCPsocket *TCPsocket;

This is an opaque data type used for TCP connections. This is a pointer, and so it could be NULL at times. NULL would indicate no socket has been established.

See Also:
3.3 TCP Sockets, 4.3 UDPsocket, 4.6 SDLNet_GenericSocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.3 UDPsocket

typedef struct _UDPsocket *UDPsocket;

This is an opaque data type used for UDP sockets. This is a pointer, and so it could be NULL at times. NULL would indicate no socket has been established.

See Also:
3.4 UDP Sockets, 4.4 UDPpacket, 4.2 TCPsocket, 4.6 SDLNet_GenericSocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.4 UDPpacket

typedef struct {
    int channel;          /* The src/dst channel of the packet */
    Uint8 *data;          /* The packet data */
    int len;              /* The length of the packet data */
    int maxlen;           /* The size of the data buffer */
    int status;           /* packet status after sending */
    IPaddress address;    /* The source/dest address of an
                                   incoming/outgoing packet */
} UDPpacket;

channel
The (software) channel number for this packet. This can also be used as a priority value for the packet. If no channel is assigned, the value is -1.
data
The data contained in this packet, this is the meat.
len
This is the meaningful length of the data in bytes.
maxlen
This is size of the data buffer, which may be larger than the meaningful length. This is only used for packet creation on the senders side.
status
This contains the number of bytes sent, or a -1 on errors, after sending. This is useless for a received packet.
address
This is the resolved IPaddress to be used when sending, or it is the remote source of a received packet.

This struct is used with UDPsockets to send and receive data. It also helps keep track of a packets sending/receiving settings and status. The channels concept helps prioritize, or segregate differring types of data packets.

See Also:
3.5 UDP Packets, 4.3 UDPsocket, 4.1 IPaddress

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.5 SDLNet_SocketSet

typedef struct _SDLNet_SocketSet *SDLNet_SocketSet;

This is an opaque data type used for socket sets. This is a pointer, and so it could be NULL at times. NULL would indicate no socket set has been created.

See Also:
3.6 Socket Sets, 4.2 TCPsocket, 4.3 UDPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.6 SDLNet_GenericSocket

typedef struct {
    int ready;
} *SDLNet_GenericSocket;

ready
non-zero when data is ready to be read, or a server socket has a connection attempt ready to be accepted.

This data type is able to be used for both UDPsocket and TCPsocket types.
After calling SDLNet_CheckSockets, if this socket is in SDLNet_SocketSet used, the ready will be set according to activity on the socket. This is the only real use for this type, as it doesn't help you know what type of socket it is.

See Also:
3.6 Socket Sets, 4.2 TCPsocket, 4.3 UDPsocket

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5. Defines

SDL_NET_MAJOR_VERSION
1
SDL_net library major number at compilation time
SDL_NET_MINOR_VERSION
2
SDL_net library minor number at compilation time
SDL_NET_PATCHLEVEL
7
SDL_net library patch level at compilation time
INADDR_ANY
0x00000000 (0.0.0.0)
used for listening on all network interfaces.
INADDR_NONE
0xFFFFFFFF (255.255.255.255)
which has limited applications.
INADDR_BROADCAST
0xFFFFFFFF (255.255.255.255)
used as destination when sending a message to all clients on a subnet that allows broadcasts.
SDLNET_MAX_UDPCHANNELS
32
The maximum number of channels on a UDP socket.
SDLNET_MAX_UDPADDRESSES
4
The maximum number of addresses bound to a single UDP socket channel

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6. Glossary

Network Byte Order
Also known as Big-Endian. Which means the most significant byte comes first in storage. Sparc and Motorola 68k based chips are MSB ordered.
(SDL defines this as SDL_BYTEORDER==SDL_BIG_ENDIAN)

Little-Endian(LSB) is stored in the opposite order, with the least significant byte first in memory. Intel and AMD are two LSB machines.
(SDL defines this as SDL_BYTEORDER==SDL_LIL_ENDIAN)

For network addresses, 1.2.3.4 is always stored as {0x01 0x02 0x03 0x04}.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Index

Jump to: B I L M N R S T U

 | Index Entry | Section
B |  |
 | Big-Endian | 6. Glossary
I |  |
 | INADDR_ANY | 5. Defines
 | INADDR_BROADCAST | 5. Defines
 | INADDR_NONE | 5. Defines
 | IPaddress | 4.1 IPaddress
L |  |
 | Little-Endian | 6. Glossary
 | LSB | 6. Glossary
M |  |
 | MSB | 6. Glossary
N |  |
 | Network Byte Order | 6. Glossary
R |  |
 | README | 1. Overview
S |  |
 | sdl-config | 2.2 Compiling
 | SDL_NET_MAJOR_VERSION | 5. Defines
 | SDL_NET_MINOR_VERSION | 5. Defines
 | SDL_NET_PATCHLEVEL | 5. Defines
 | SDL_NET_VERSION | 3.1.1 SDLNet_Linked_Version
 | SDLNet_AddSocket | 3.6.3 SDLNet_AddSocket
 | SDLNet_AllocPacket | 3.5.1 SDLNet_AllocPacket
 | SDLNet_AllocPacketV | 3.5.4 SDLNet_AllocPacketV
 | SDLNet_AllocSocketSet | 3.6.1 SDLNet_AllocSocketSet
 | SDLNet_CheckSockets | 3.6.5 SDLNet_CheckSockets
 | SDLNet_DelSocket | 3.6.4 SDLNet_DelSocket
 | SDLNet_FreePacket | 3.5.3 SDLNet_FreePacket
 | SDLNet_FreePacketV | 3.5.5 SDLNet_FreePacketV
 | SDLNet_FreeSocketSet | 3.6.2 SDLNet_FreeSocketSet
 | SDLNet_GenericSocket | 4.6 SDLNet_GenericSocket
 | SDLNet_GetError | 3.1.4 SDLNet_GetError
 | SDLNet_Init | 3.1.2 SDLNet_Init
 | SDLNet_Linked_Version | 3.1.1 SDLNet_Linked_Version
 | SDLNET_MAX_UDPADDRESSES | 5. Defines
 | SDLNET_MAX_UDPCHANNELS | 5. Defines
 | SDLNet_Quit | 3.1.3 SDLNet_Quit
 | SDLNet_Read16 | 3.1.7 SDLNet_Read16
 | SDLNet_Read32 | 3.1.8 SDLNet_Read32
 | SDLNet_ResizePacket | 3.5.2 SDLNet_ResizePacket
 | SDLNet_ResolveHost | 3.2.1 SDLNet_ResolveHost
 | SDLNet_ResolveIP | 3.2.2 SDLNet_ResolveIP
 | SDLNet_SocketReady | 3.6.6 SDLNet_SocketReady
 | SDLNet_SocketSet | 4.5 SDLNet_SocketSet
 | SDLNet_TCP_Accept | 3.3.3 SDLNet_TCP_Accept
 | SDLNet_TCP_AddSocket | 3.6.3 SDLNet_AddSocket
 | SDLNet_TCP_Close | 3.3.2 SDLNet_TCP_Close
 | SDLNet_TCP_DelSocket | 3.6.4 SDLNet_DelSocket
 | SDLNet_TCP_GetPeerAddress | 3.3.4 SDLNet_TCP_GetPeerAddress
 | SDLNet_TCP_Open | 3.3.1 SDLNet_TCP_Open
 | SDLNet_TCP_Recv | 3.3.6 SDLNet_TCP_Recv
 | SDLNet_TCP_Send | 3.3.5 SDLNet_TCP_Send
 | SDLNet_UDP_AddSocket | 3.6.3 SDLNet_AddSocket
 | SDLNet_UDP_Bind | 3.4.3 SDLNet_UDP_Bind
 | SDLNet_UDP_Close | 3.4.2 SDLNet_UDP_Close
 | SDLNet_UDP_DelSocket | 3.6.4 SDLNet_DelSocket
 | SDLNet_UDP_GetPeerAddress | 3.4.5 SDLNet_UDP_GetPeerAddress
 | SDLNet_UDP_Open | 3.4.1 SDLNet_UDP_Open
 | SDLNet_UDP_Recv | 3.4.7 SDLNet_UDP_Recv
 | SDLNet_UDP_RecvV | 3.4.9 SDLNet_UDP_RecvV
 | SDLNet_UDP_Send | 3.4.6 SDLNet_UDP_Send
 | SDLNet_UDP_SendV | 3.4.8 SDLNet_UDP_SendV
 | SDLNet_UDP_Unbind | 3.4.4 SDLNet_UDP_Unbind
 | SDLNet_Write16 | 3.1.5 SDLNet_Write16
 | SDLNet_Write32 | 3.1.6 SDLNet_Write32
T |  |
 | TCPsocket | 4.2 TCPsocket
U |  |
 | UDPpacket | 4.4 UDPpacket
 | UDPsocket | 4.3 UDPsocket

Jump to: B I L M N R S T U

[Top] [Contents] [Index] [ ? ]

Table of Contents

    1. Overview
    2. Getting Started
      2.1 Includes
      2.2 Compiling
    3. Functions
      3.1 General
        3.1.1 SDLNet_Linked_Version
        3.1.2 SDLNet_Init
        3.1.3 SDLNet_Quit
        3.1.4 SDLNet_GetError
        3.1.5 SDLNet_Write16
        3.1.6 SDLNet_Write32
        3.1.7 SDLNet_Read16
        3.1.8 SDLNet_Read32
      3.2 Name Resolution
        3.2.1 SDLNet_ResolveHost
        3.2.2 SDLNet_ResolveIP
      3.3 TCP Sockets
        3.3.1 SDLNet_TCP_Open
        3.3.2 SDLNet_TCP_Close
        3.3.3 SDLNet_TCP_Accept
        3.3.4 SDLNet_TCP_GetPeerAddress
        3.3.5 SDLNet_TCP_Send
        3.3.6 SDLNet_TCP_Recv
      3.4 UDP Sockets
        3.4.1 SDLNet_UDP_Open
        3.4.2 SDLNet_UDP_Close
        3.4.3 SDLNet_UDP_Bind
        3.4.4 SDLNet_UDP_Unbind
        3.4.5 SDLNet_UDP_GetPeerAddress
        3.4.6 SDLNet_UDP_Send
        3.4.7 SDLNet_UDP_Recv
        3.4.8 SDLNet_UDP_SendV
        3.4.9 SDLNet_UDP_RecvV
      3.5 UDP Packets
        3.5.1 SDLNet_AllocPacket
        3.5.2 SDLNet_ResizePacket
        3.5.3 SDLNet_FreePacket
        3.5.4 SDLNet_AllocPacketV
        3.5.5 SDLNet_FreePacketV
      3.6 Socket Sets
        3.6.1 SDLNet_AllocSocketSet
        3.6.2 SDLNet_FreeSocketSet
        3.6.3 SDLNet_AddSocket
        3.6.4 SDLNet_DelSocket
        3.6.5 SDLNet_CheckSockets
        3.6.6 SDLNet_SocketReady
    4. Types
      4.1 IPaddress
      4.2 TCPsocket
      4.3 UDPsocket
      4.4 UDPpacket
      4.5 SDLNet_SocketSet
      4.6 SDLNet_GenericSocket
    5. Defines
    6. Glossary
    Index
[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. Overview
2. Getting Started
3. Functions
4. Types
5. Defines
6. Glossary
Index
[Top] [Contents] [Index] [ ? ]

About this document

This document was generated on November, 3 2009 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated on November, 3 2009 using texi2html


SDL_ttf 2.0.10

1. Overview The README from the SDL_ttf distribution

2. Getting Started Using SDL_ttf

3. Functions | Functions supported by the SDL_ttf API
4. Types | Types used with the SDL_ttf API
5. Defines | Defined values/macros in the SDL_ttf API

6. Glossary Terms used in this document

Index Index of selected words
[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

1. Overview

A Little Bit About Me

I am currently, as I write this document, a programmer for Raytheon. There I do all sorts of communications, network, GUI, and other general programming tasks in C/C++ on the Solaris and sometimes Linux Operating Systems. I've used SDL_ttf as one of the many methods of putting text on my SDL applications, and use it in my own SDL GUI code as well. While this document doesn't explain how and where to get fonts to use, it will explain how to use them with SDL_ttf.

Feel free to contact me: JonathanCAtkins@gmail.com

The latest version of this library is available from:
SDL_ttf Homepage

I am also usually on IRC at irc.freenode.net in the #SDL channel as LIM

This is the README in the SDL_ttf source archive.

This library is a wrapper around the excellent FreeType 1.2 library, available at: Freetype Homepage

WARNING: There may be patent issues with using the FreeType library. Check the FreeType website for up-to-date details.

This library allows you to use TrueType fonts to render text in SDL applications.

To make the library, first install the FreeType library, then type 'make' to build the SDL truetype library and 'make all' to build the demo application.

Be careful when including fonts with your application, as many of them are copyrighted. The Microsoft fonts, for example, are not freely redistributable and even the free "web" fonts they provide are only redistributable in their special executable installer form (May 1998). There are plenty of freeware and shareware fonts available on the Internet though, which may suit your purposes.

Please see the file "COPYING" for license information for this library.

Enjoy! -Sam Lantinga slouken@devolution.com (5/1/98)

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2. Getting Started

This assumes you have gotten SDL_ttf and installed it on your system. SDL_ttf has an INSTALL document in the source distribution to help you get it compiled and installed.

Generally, installation consists of:

./configure
make
make install

SDL_ttf supports loading fonts from TrueType font files, normally ending in .ttf, though some .fon files are also valid for use. Note that most fonts are copyrighted, check the license on the font before you use and redistribute it.

Some free font sources are:

  • Free UCS Outline Fonts
  • Fonthead Design
  • Bitstream Vera Fonts
  • FreeUniFont
  • 1001 Fonts
  • Google!

You may also want to look at some demonstration code which may be downloaded from:
http://www.jonatkins.org/SDL_ttf/

2.1 Includes | The include files to use for SDL_ttf
2.2 Compiling | Using the SDL_ttf library and header file.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.1 Includes

To use SDL_ttf functions in a C/C++ source code file, you must use the SDL_ttf.h include file:

#include "SDL_ttf.h"

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

2.2 Compiling

To link with SDL_ttf you should use sdl-config to get the required SDL compilation options. After that, compiling with SDL_ttf is quite easy.
Note: Some systems may not have the SDL_ttf library and include file in the same place as the SDL library and includes are located, in that case you will need to add more -I and -L paths to these command lines. All examples are gcc and perhaps UNIX specific, but adaptable to many compilers and Operating Systems.

Simple Example for compiling to an object file:

gcc -c `sdl-config --cflags` mysource.c

Simple Example for linking an executable (Unix style has no .exe):

gcc -o myprogram mysource.o `sdl-config --libs` -lSDL_ttf

Now myprogram is ready to run.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3. Functions

These are the functions in the SDL_ttf API.

3.1 General | API activation, info, and error handling
3.2 Management | Loading fonts from files or memory
3.3 Attributes | Getting and Setting font attributes
3.4 Render | Drawing strings and glyphs with a font

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1 General

These functions are core elements in SDL_ttf.

Info
3.1.1 TTF_Linked_Version Get runtime version number
Activation
3.1.2 TTF_Init | Initialize API
3.1.3 TTF_WasInit | Query API initialization status
3.1.4 TTF_Quit | Cleanup API
Errors
3.1.5 TTF_SetError | Set the current error string
3.1.6 TTF_GetError | Get the current error string

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.1 TTF_Linked_Version

const SDL_version *TTF_Linked_Version()
void SDL_TTF_VERSION(SDL_version *compile_version)

This works similar to SDL_Linked_Version and SDL_VERSION.
Using these you can compare the runtime version to the version that you compiled with.
No prior initialization needs to be done before these function/macros are used.

SDL_version compile_version;
const SDL_version *link_version=TTF_Linked_Version();
SDL_TTF_VERSION(&compile_version);
printf("compiled with SDL_ttf version: %d.%d.%d\n",
        compile_version.major,
        compile_version.minor,
        compile_version.patch);
printf("running with SDL_ttf version: %d.%d.%d\n",
        link_version->major,
        link_version->minor,
        link_version->patch);

See Also:
3.1.2 TTF_Init

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.2 TTF_Init

int TTF_Init()

Initialize the truetype font API.
This must be called before using other functions in this library, except TTF_WasInit.
SDL does not have to be initialized before this call.

Returns: 0 on success, -1 on any error

if(TTF_Init()==-1) {
    printf("TTF_Init: %s\n", TTF_GetError());
    exit(2);
}

See Also:
3.1.4 TTF_Quit, 3.1.3 TTF_WasInit

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.3 TTF_WasInit

int TTF_WasInit()

Query the initilization status of the truetype font API.
You may, of course, use this before TTF_Init to avoid initializing twice in a row. Or use this to determine if you need to call TTF_Quit.

Returns: 1 if already initialized, 0 if not initialized.

if(!TTF_WasInit() && TTF_Init()==-1) {
    printf("TTF_Init: %s\n", TTF_GetError());
    exit(1);
}

See Also:
3.1.2 TTF_Init, 3.1.4 TTF_Quit

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.4 TTF_Quit

void TTF_Quit()

Shutdown and cleanup the truetype font API.
After calling this the SDL_ttf functions should not be used, excepting TTF_WasInit. You may, of course, use TTF_Init to use the functionality again.

TTF_Quit();
// you could SDL_Quit(); here...or not.

See Also:
3.1.2 TTF_Init, 3.1.3 TTF_WasInit

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.5 TTF_SetError

void TTF_SetError(const char *fmt, ...)

This is really a defined macro for SDL_SetError, which sets the error string which may be fetched with TTF_GetError (or SDL_GetError). This functions acts like printf, except that it is limited to SDL_ERRBUFIZE(1024) chars in length. It only accepts the following format types: %s, %d, %f, %p. No flags, precisions, field widths, nor length modifiers, are supported in the format. For any more specifics read the SDL docs.

int myfunc(int i) {
    TTF_SetError("myfunc is not implemented! %d was passed in.",i);
    return(-1);
}

See Also:
3.1.6 TTF_GetError

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.1.6 TTF_GetError

char *TTF_GetError()

This is really a defined macro for SDL_GetError. It returns the last error set by TTF_SetError (or SDL_SetError) as a string. Use this to tell the user what happened when an error status has been returned from an SDL_ttf function call.

Returns: a char pointer (string) containing a human readable version or the reason for the last error that occured.

printf("Oh My Goodness, an error : %s", TTF_GetError());

See Also:
3.1.5 TTF_SetError

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2 Management

These functions deal with loading and freeing a TTF_Font.

Loading
3.2.1 TTF_OpenFont | From a file
3.2.2 TTF_OpenFontRW | Using RWops
3.2.3 TTF_OpenFontIndex | From a file, with an index
3.2.4 TTF_OpenFontIndexRW | From memory, with an index
Freeing
3.2.5 TTF_CloseFont Free a loaded font

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.1 TTF_OpenFont

TTF_Font *TTF_OpenFont(const char *file, int ptsize)

file
File name to load font from.
ptsize
Point size (based on 72DPI) to load font as. This basically translates to pixel height.

Load file for use as a font, at ptsize size. This is actually TTF_OpenFontIndex(file, ptsize, 0). This can load TTF and FON files.

Returns: a pointer to the font as a TTF_Font. NULL is returned on errors.

// load font.ttf at size 16 into font
TTF_Font *font;
font=TTF_OpenFont("font.ttf", 16);
if(!font) {
    printf("TTF_OpenFont: %s\n", TTF_GetError());
    // handle error
}

See Also:
3.2.3 TTF_OpenFontIndex, 3.2.2 TTF_OpenFontRW, 3.2.5 TTF_CloseFont

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.2 TTF_OpenFontRW

TTF_Font *TTF_OpenFontRW(SDL_RWops *src, int freesrc, int ptsize)

src
The source SDL_RWops as a pointer. The font is loaded from this.
freesrc
A non-zero value means it will automatically close and free the src for you after it finishes using the src, even if a noncritical error occured.
ptsize
Point size (based on 72DPI) to load font as. This basically translates to pixel height.

Load src for use as a font, at ptsize size. This is actually TTF_OpenFontIndexRW(src, freesrc, ptsize, 0) This can load TTF and FON formats. Using SDL_RWops is not covered here, but they enable you to load from almost any source.

NOTE: src is not checked for NULL, so be careful.

Returns: a pointer to the font as a TTF_Font. NULL is returned on errors.

// load font.ttf at size 16 into font
TTF_Font *font;
font=TTF_OpenFontRW(SDL_RWFromFile("font.ttf"), 1, 16);
if(!font) {
    printf("TTF_OpenFontRW: %s\n", TTF_GetError());
    // handle error
}
Note that this is unsafe because we don't check the validity of the SDL_RWFromFile's returned pointer.

See Also:
3.2.4 TTF_OpenFontIndexRW, 3.2.1 TTF_OpenFont, 3.2.5 TTF_CloseFont

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.3 TTF_OpenFontIndex

TTF_Font *TTF_OpenFontIndex(const char *file, int ptsize, long index)

file
File name to load font from.
ptsize
Point size (based on 72DPI) to load font as. This basically translates to pixel height.
index
choose a font face from a file containing multiple font faces. The first face is always index 0.

Load file, face index, for use as a font, at ptsize size. This is actually TTF_OpenFontIndexRW(SDL_RWFromFile(file), ptsize, index), but checks that the RWops it creates is not NULL. This can load TTF and FON files.

Returns: a pointer to the font as a TTF_Font. NULL is returned on errors.

// load font.ttf, face 0, at size 16 into font
TTF_Font *font;
font=TTF_OpenFontIndex("font.ttf", 16, 0);
if(!font) {
    printf("TTF_OpenFontIndex: %s\n", TTF_GetError());
    // handle error
}

See Also:
3.2.4 TTF_OpenFontIndexRW, 3.2.1 TTF_OpenFont, 3.2.5 TTF_CloseFont

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.4 TTF_OpenFontIndexRW

TTF_Font *TTF_OpenFontIndexRW(SDL_RWops *src, int freesrc, int ptsize, long index)

src
The source SDL_RWops as a pointer. The font is loaded from this.
freesrc
A non-zero value means it will automatically close and free the src for you after it finishes using the src, even if a noncritical error occured.
ptsize
Point size (based on 72DPI) to load font as. This basically translates to pixel height.
index
Choose a font face from a file containing multiple font faces. The first face is always index 0.

Load src, face index, for use as a font, at ptsize size. This can load TTF and FON formats.
Using SDL_RWops is not covered here, but they enable you to load from almost any source.

NOTE: src is not checked for NULL, so be careful.

Returns: a pointer to the font as a TTF_Font. NULL is returned on errors.

// load font.ttf, face 0, at size 16 into font
TTF_Font *font;
font=TTF_OpenFontRW(SDL_RWFromFile("font.ttf"), 1, 16, 0);
if(!font) {
    printf("TTF_OpenFontIndexRW: %s\n", TTF_GetError());
    // handle error
}
Note that this is unsafe because we don't check the validity of the SDL_RWFromFile's returned pointer.

See Also:
3.2.3 TTF_OpenFontIndex, 3.2.2 TTF_OpenFontRW, 3.2.5 TTF_CloseFont

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.2.5 TTF_CloseFont

void TTF_CloseFont(TTF_Font *font)

font
Pointer to the TTF_Font to free.

Free the memory used by font, and free font itself as well. Do not use font after this without loading a new font to it.

// free the font
// TTF_Font *font;
TTF_CloseFont(font);
font=NULL; // to be safe...

See Also:
3.2.1 TTF_OpenFont, 3.2.2 TTF_OpenFontRW, 3.2.3 TTF_OpenFontIndex, 3.2.4 TTF_OpenFontIndexRW

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3 Attributes

These functions deal with TTF_Font, and global, attributes.

See the end of 3.3.19 TTF_GlyphMetrics for info on how the metrics work.

Global Attributes
3.3.1 TTF_ByteSwappedUNICODE Set default UNICODE byte swapping mode
Font Style
3.3.2 TTF_GetFontStyle | Get font render style
3.3.3 TTF_SetFontStyle | Set font render style
3.3.4 TTF_GetFontOutline | Get font outline width
3.3.5 TTF_SetFontOutline | Set font outline width
Font Settings
3.3.6 TTF_GetFontHinting | Get freetype hinter setting
3.3.7 TTF_SetFontHinting | Set freetype hinter setting
3.3.8 TTF_GetFontKerning | Get freetype kerning setting
3.3.9 TTF_SetFontKerning | Set freetype kerning setting
Font Metrics
3.3.10 TTF_FontHeight | Get font maximum total height
3.3.11 TTF_FontAscent | Get font highest ascent (height above base)
3.3.12 TTF_FontDescent | Get font lowest descent (height below base)
3.3.13 TTF_FontLineSkip | Get font recommended line spacing
Face Attributes
3.3.14 TTF_FontFaces | Get the number of faces in a font
3.3.15 TTF_FontFaceIsFixedWidth | Get whether font is monospaced or not
3.3.16 TTF_FontFaceFamilyName | Get current font face family name string
3.3.17 TTF_FontFaceStyleName | Get current font face style name string
Glyphs
3.3.18 TTF_GlyphIsProvided | Get individual font glyph availability
3.3.19 TTF_GlyphMetrics | Get individual font glyph metrics
Text Metrics
3.3.20 TTF_SizeText | Get size of LATIN1 text string as would be rendered
3.3.21 TTF_SizeUTF8 | Get size of UTF8 text string as would be rendered
3.3.22 TTF_SizeUNICODE | Get size of UNICODE text string as would be rendered

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.1 TTF_ByteSwappedUNICODE

void TTF_ByteSwappedUNICODE(int swapped)

swapped
if non-zero then UNICODE data is byte swapped relative to the CPU's native endianness.
if zero, then do not swap UNICODE data, use the CPU's native endianness.

This function tells SDL_ttf whether UNICODE (Uint16 per character) text is generally byteswapped. A UNICODE_BOM_NATIVE or UNICODE_BOM_SWAPPED character in a string will temporarily override this setting for the remainder of that string, however this setting will be restored for the next one. The default mode is non-swapped, native endianness of the CPU.

// Turn on byte swapping for UNICODE text
TTF_ByteSwappedUNICODE(1);

See Also:
5. Defines

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.2 TTF_GetFontStyle

int TTF_GetFontStyle(TTF_Font *font)

font
The loaded font to get the style of.

Get the rendering style of the loaded font.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The style as a bitmask composed of the following masks:
TTF_STYLE_BOLD
TTF_STYLE_ITALIC
TTF_STYLE_UNDERLINE
TTF_STYLE_STRIKETHROUGH
If no style is set then TTF_STYLE_NORMAL is returned.

// get the loaded font's style
//TTF_Font *font;
int style;
style=TTF_GetFontStyle(font);
printf("The font style is:");
if(style==TTF_STYLE_NORMAL)
    printf(" normal");
else {
    if(style&TTF_STYLE_BOLD)
        printf(" bold");
    if(style&TTF_STYLE_ITALIC)
        printf(" italic");
    if(style&TTF_STYLE_UNDERLINE)
        printf(" underline");
    if(style&TTF_STYLE_STRIKETHROUGH)
        printf(" strikethrough");
}
printf("\n");

See Also:
3.3.3 TTF_SetFontStyle,
5. Defines

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.3 TTF_SetFontStyle

void TTF_SetFontStyle(TTF_Font *font, int style)

font
The loaded font to set the style of.
style
The style as a bitmask composed of the following masks:
TTF_STYLE_BOLD
TTF_STYLE_ITALIC
TTF_STYLE_UNDERLINE
TTF_STYLE_STRIKETHROUGH
If no style is desired then use TTF_STYLE_NORMAL, which is the default.

Set the rendering style of the loaded font.

NOTE: Passing a NULL font into this function will cause a segfault.

NOTE: This will flush the internal cache of previously rendered glyphs, even if there is no change in style, so it may be best to check the current style using TTF_GetFontStyle first.

NOTE: TTF_STYLE_UNDERLINE may cause surfaces created by TTF_RenderGlyph_* functions to be extended vertically, downward only, to encompass the underline if the original glyph metrics didn't allow for the underline to be drawn below. This does not change the math used to place a glyph using glyph metrics.
On the other hand TTF_STYLE_STRIKETHROUGH doesn't extend the glyph, since this would invalidate the metrics used to position the glyph when blitting, because they would likely be extended vertically upward. There is perhaps a workaround, but it would require programs to be smarter about glyph blitting math than they are currently designed for.
Still, sometimes the underline or strikethrough may be outside of the generated surface, and thus not visible when blitted to the screen. In this case, you should probably turn off these styles and draw your own strikethroughs and underlines.

// set the loaded font's style to bold italics
//TTF_Font *font;
TTF_SetFontStyle(font, TTF_STYLE_BOLD|TTF_STYLE_ITALIC);

// render some text in bold italics...

// set the loaded font's style back to normal
TTF_SetFontStyle(font, TTF_STYLE_NORMAL);

See Also:
3.3.2 TTF_GetFontStyle,
5. Defines

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.4 TTF_GetFontOutline

int TTF_GetFontOutline(TTF_Font *font)

font
The loaded font to get the outline size of.

Get the current outline size of the loaded font.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The size of the outline currently set on the font, in pixels.

// get the loaded font's outline width
//TTF_Font *font;
int outline=TTF_GetFontOutline(font);
printf("The font outline width is %d pixels\n",outline);

See Also:
3.3.5 TTF_SetFontOutline,
3.3.2 TTF_GetFontStyle

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.5 TTF_SetFontOutline

void TTF_SetFontOutline(TTF_Font *font, int outline)

font
The loaded font to set the outline size of.
outline
The size of outline desired, in pixels.
Use 0(zero) to turn off outlining.

Set the outline pixel width of the loaded font.

NOTE: Passing a NULL font into this function will cause a segfault.

NOTE: This will flush the internal cache of previously rendered glyphs, even if there is no change in outline size, so it may be best to check the current outline size using TTF_GetFontOutline first.

// set the loaded font's outline to 1 pixel wide
//TTF_Font *font;
TTF_SetFontOutline(font, 1);

// render some outlined text...

// set the loaded font's outline back to normal
TTF_SetFontOutline(font, 0);

See Also:
3.3.4 TTF_GetFontOutline,
3.3.3 TTF_SetFontStyle

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.6 TTF_GetFontHinting

int TTF_GetFontHinting(TTF_Font *font)

font
The loaded font to get the hinting setting of.

Get the current hinting setting of the loaded font.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The hinting type matching one of the following defined values:
TTF_HINTING_NORMAL
TTF_HINTING_LIGHT
TTF_HINTING_MONO
TTF_HINTING_NONE
If no hinting is set then TTF_HINTING_NORMAL is returned.

// get the loaded font's hinting setting
//TTF_Font *font;
int hinting=TTF_GetFontHinting(font);
printf("The font hinting is currently set to %s\n",
        hinting==0?"Normal":
        hinting==1?"Light":
        hinting==2?"Mono":
        hinting==3?"None":
        "Unknonwn");

See Also:
3.3.7 TTF_SetFontHinting,
5. Defines,
see section Hinting,
Font Hinting @ Wikipedia,
FreeType Hinting and Bitmap rendering,
FreeType Hinting Modes

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.7 TTF_SetFontHinting

void TTF_SetFontHinting(TTF_Font *font, int hinting)

font
The loaded font to set the outline size of.
hinting
The hinting setting desired, which is one of:
TTF_HINTING_NORMAL
TTF_HINTING_LIGHT
TTF_HINTING_MONO
TTF_HINTING_NONE
The default is TTF_HINTING_NORMAL.

Set the hinting of the loaded font. You should experiment with this setting if you know which font you are using beforehand, especially when using smaller sized fonts. If the user is selecting a font, you may wish to let them select the hinting mode for that font as well.

NOTE: Passing a NULL font into this function will cause a segfault.

NOTE: This will flush the internal cache of previously rendered glyphs, even if there is no change in hinting, so it may be best to check the current hinting by using TTF_GetFontHinting first.

// set the loaded font's hinting to optimized for monochrome rendering
//TTF_Font *font;
TTF_SetFontHinting(font, TTF_HINTING_MONO);

// render some monochrome text...

// set the loaded font's hinting back to normal
TTF_SetFontHinting(font, TTF_HINTING_NORMAL);

See Also:
3.3.6 TTF_GetFontHinting,
5. Defines,
see section Hinting,
Font Hinting @ Wikipedia,
FreeType Hinting and Bitmap rendering,
FreeType Hinting Modes

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.8 TTF_GetFontKerning

int TTF_GetFontKerning(TTF_Font *font)

font
The loaded font to get the kerning setting of.

Get the current kerning setting of the loaded font.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: 0(zero) if kerning is disabled. A non-zero value is returned when enabled. The default for a newly loaded font is enabled(1).

// get the loaded font's kerning setting
//TTF_Font *font;
int kerning=TTF_GetFontKerning(font);
printf("The font kerning is currently set to %s\n",
        kerning==0?"Off":"On");

See Also:
3.3.9 TTF_SetFontKerning,
see section Kerning,
Kerning @ Wikipedia

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.9 TTF_SetFontKerning

void TTF_SetFontKerning(TTF_Font *font, int allowed)

font
The loaded font to set the outline size of.
allowed
0 to diable kerning.
non-zero to enable kerning. The default is 1, enabled.

Set whther to use kerning when rendering the loaded font. This has no effect on individual glyphs, but rather when rendering whole strings of characters, at least a word at a time. Perhaps the only time to disable this is when kerning is not working for a specific font, resulting in overlapping glyphs or abnormal spacing within words.

NOTE: Passing a NULL font into this function will cause a segfault.

// turn off kerning on the loaded font
//TTF_Font *font;
TTF_SetFontKerning(font, 0);

// render some text string...

// turn kerning back on for the loaded font
TTF_SetFontKerning(font, 1);

See Also:
3.3.8 TTF_GetFontKerning,
see section Kerning,
Kerning @ Wikipedia

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.10 TTF_FontHeight

int TTF_FontHeight(const TTF_Font *font)

font
The loaded font to get the max height of.

Get the maximum pixel height of all glyphs of the loaded font. You may use this height for rendering text as close together vertically as possible, though adding at least one pixel height to it will space it so they can't touch. Remember that SDL_ttf doesn't handle multiline printing, so you are responsible for line spacing, see the TTF_FontLineSkip as well.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The maximum pixel height of all glyphs in the font.

// get the loaded font's max height
//TTF_Font *font;
printf("The font max height is: %d\n", TTF_FontHeight(font));

See Also:
3.3.11 TTF_FontAscent,
3.3.12 TTF_FontDescent,
3.3.13 TTF_FontLineSkip,
3.3.19 TTF_GlyphMetrics

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.11 TTF_FontAscent

int TTF_FontAscent(const TTF_Font *font)

font
The loaded font to get the ascent (height above baseline) of.

Get the maximum pixel ascent of all glyphs of the loaded font. This can also be interpreted as the distance from the top of the font to the baseline.
It could be used when drawing an individual glyph relative to a top point, by combining it with the glyph's maxy metric to resolve the top of the rectangle used when blitting the glyph on the screen.

rect.y = top + TTF_FontAscent(font) - glyph_metric.maxy;

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The maximum pixel ascent of all glyphs in the font.

// get the loaded font's max ascent
//TTF_Font *font;

printf("The font ascent is: %d\n", TTF_FontAscent(font));

See Also:
3.3.10 TTF_FontHeight,
3.3.12 TTF_FontDescent,
3.3.13 TTF_FontLineSkip,
3.3.19 TTF_GlyphMetrics

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.12 TTF_FontDescent

int TTF_FontDescent(const TTF_Font *font)

font
The loaded font to get the descent (height below baseline) of.

Get the maximum pixel descent of all glyphs of the loaded font. This can also be interpreted as the distance from the baseline to the bottom of the font.
It could be used when drawing an individual glyph relative to a bottom point, by combining it with the glyph's maxy metric to resolve the top of the rectangle used when blitting the glyph on the screen.

rect.y = bottom - TTF_FontDescent(font) - glyph_metric.maxy;

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The maximum pixel height of all glyphs in the font.

// get the loaded font's max descent
//TTF_Font *font;

printf("The font descent is: %d\n", TTF_FontDescent(font));

See Also:
3.3.10 TTF_FontHeight,
3.3.11 TTF_FontAscent,
3.3.13 TTF_FontLineSkip,
3.3.19 TTF_GlyphMetrics

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.13 TTF_FontLineSkip

int TTF_FontLineSkip(const TTF_Font *font)

font
The loaded font to get the line skip height of.

Get the recommended pixel height of a rendered line of text of the loaded font. This is usually larger than the TTF_FontHeight of the font.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The maximum pixel height of all glyphs in the font.

// get the loaded font's line skip height
//TTF_Font *font;

printf("The font line skip is: %d\n", TTF_FontLineSkip(font));

See Also:
3.3.10 TTF_FontHeight,
3.3.11 TTF_FontAscent,
3.3.12 TTF_FontDescent,
3.3.19 TTF_GlyphMetrics

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.14 TTF_FontFaces

long TTF_FontFaces(const TTF_Font *font)

font
The loaded font to get the number of available faces from.

Get the number of faces ("sub-fonts") available in the loaded font. This is a count of the number of specific fonts (based on size and style and other typographical features perhaps) contained in the font itself. It seems to be a useless fact to know, since it can't be applied in any other SDL_ttf functions.
NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The number of faces in the font.

// get the loaded font's number of faces
//TTF_Font *font;

printf("The number of faces in the font is: %ld\n", TTF_FontFaces(font));

See Also:
3.3.15 TTF_FontFaceIsFixedWidth,
3.3.16 TTF_FontFaceFamilyName,
3.3.17 TTF_FontFaceStyleName

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.15 TTF_FontFaceIsFixedWidth

int TTF_FontFaceIsFixedWidth(const TTF_Font *font)

font
The loaded font to get the fixed width status of.

Test if the current font face of the loaded font is a fixed width font. Fixed width fonts are monospace, meaning every character that exists in the font is the same width, thus you can assume that a rendered string's width is going to be the result of a simple calculation:
glyph_width * string_length
NOTE: Passing a NULL font into this function will cause a segfault.

Returns: >0 if font is a fixed width font. 0 if not a fixed width font.

// get the loaded font's face fixed status
//TTF_Font *font;

if(TTF_FontFaceIsFixedWidth(font))
    printf("The font is fixed width.\n");
else
    printf("The font is not fixed width.\n");

See Also:
3.3.14 TTF_FontFaces,
3.3.16 TTF_FontFaceFamilyName,
3.3.17 TTF_FontFaceStyleName,
3.3.19 TTF_GlyphMetrics

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.16 TTF_FontFaceFamilyName

char * TTF_FontFaceFamilyName(const TTF_Font *font)

font
The loaded font to get the current face family name of.

Get the current font face family name from the loaded font. This function may return a NULL pointer, in which case the information is not available.
NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The current family name of of the face of the font, or NULL perhaps.

// get the loaded font's face name
//TTF_Font *font;

char *familyname=TTF_FontFaceFamilyName(font);
if(familyname)
    printf("The family name of the face in the font is: %s\n", familyname);

See Also:
3.3.14 TTF_FontFaces,
3.3.15 TTF_FontFaceIsFixedWidth,
3.3.17 TTF_FontFaceStyleName

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.17 TTF_FontFaceStyleName

char * TTF_FontFaceStyleName(const TTF_Font *font)

font
The loaded font to get the current face style name of.

Get the current font face style name from the loaded font. This function may return a NULL pointer, in which case the information is not available.
NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The current style name of of the face of the font, or NULL perhaps.

// get the loaded font's face style name
//TTF_Font *font;

char *stylename=TTF_FontFaceStyleName(font);
if(stylename)
    printf("The name of the face in the font is: %s\n", stylename);

See Also:
3.3.14 TTF_FontFaces,
3.3.15 TTF_FontFaceIsFixedWidth,
3.3.16 TTF_FontFaceFamilyName

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.18 TTF_GlyphIsProvided

int TTF_GlyphIsProvided(const TTF_Font *font, Uint16 ch)

font
The loaded font to get the glyph availability in.
ch
the unicode character to test glyph availability of.

Get the status of the availability of the glyph for ch from the loaded font.
NOTE: Passing a NULL font into this function will cause a segfault.

Returns: the index of the glyph for ch in font, or 0 for an undefined character code.

// check for a glyph for 'g' in the loaded font
//TTF_Font *font;

int index=TTF_GlyphIsProvided(font,'g');
if(!index)
    printf("There is no 'g' in the loaded font!\n");

See Also:
3.3.19 TTF_GlyphMetrics

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.19 TTF_GlyphMetrics

int TTF_GlyphMetrics(TTF_Font *font, Uint16 ch, int *minx, int *maxx, int *miny, int *maxy, int *advance)

font
The loaded font from which to get the glyph metrics of ch.
ch
the UNICODE char to get the glyph metrics for.
minx
pointer to int to store the returned minimum X offset into, or NULL when no return value desired.
maxx
pointer to int to store the returned maximum X offset into, or NULL when no return value desired.
miny
pointer to int to store the returned minimum Y offset into, or NULL when no return value desired.
maxy
pointer to int to store the returned maximum Y offset into, or NULL when no return value desired.
advance
pointer to int to store the returned advance offset into, or NULL when no return value desired.

Get desired glyph metrics of the UNICODE chargiven in ch from the loaded font.
NOTE: Passing a NULL font into this function will cause a segfault.

Returns: 0 on success, with all non-NULL parameters set to the glyph metric as appropriate. -1 on errors, such as when the glyph named by ch does not exist in the font.

// get the glyph metric for the letter 'g' in a loaded font
//TTF_Font *font;
int minx,maxx,miny,maxy,advance;
if(TTF_GlyphMetrics(font,'g',&minx,&maxx,&miny,&maxy,&advance)==-1)
    printf("%s\n",TTF_GetError());
else {
    printf("minx    : %d\n",minx);
    printf("maxx    : %d\n",maxx);
    printf("miny    : %d\n",miny);
    printf("maxy    : %d\n",maxy);
    printf("advance : %d\n",advance);
}

This diagram shows the relationships between the values:

Here's how the numbers look:
TTF_FontHeight       : 53
TTF_FontAscent       : 38
TTF_FontDescent      : -14
TTF_FontLineSkip     : 55
TTF_GlyphMetrics('g'):
        minx=1
        maxx=15
        miny=-7
        maxy=15
        advance=16

We see from the Line Skip that each line of text is 55 pixels high, including spacing for this font.
The Ascent-Descent=52, so there seems to be 3 pixels worth of space between lines for this font.

Let's say we want to draw the surface of glyph 'g' (retrived via 3.4.4 TTF_RenderGlyph_Solid or a similar function), at coordinates (X,Y) for the top left corner of the desired location. Here's the math using glyph metrics:
//SDL_Surface *glyph,*screen;
SDL_Rect rect;
int minx,maxy,advance;
TTF_GlyphMetrics(font,'g',&minx,NULL,NULL,&maxy,&advance);
rect.x=X+minx;
rect.y=Y+TTF_FontAscent(font)-maxy;
SDL_BlitSurface(glyph,NULL,screen,&rect);
X+=advance;

Let's say we want to draw the same glyph at coordinates (X,Y) for the origin (on the baseline) of the desired location. Here's the math using glyph metrics:
//TTF_Font *font;
//SDL_Surface *glyph,*screen;
SDL_Rect rect;
int minx,maxy,advance;
TTF_GlyphMetrics(font,'g',&minx,NULL,NULL,&maxy,&advance);
rect.x=X+minx;
rect.y=Y-maxy;
SDL_BlitSurface(glyph,NULL,screen,&rect);
X+=advance;

NOTE: The only difference between these example is the +TTF_FontAscent(font) used in the top-left corner algorithm. NOTE: These examples assume that 'g' is present in the font!
NOTE: In practice you may want to also subtract TTF_GetFontOutline(font) from your X and Y coordinates to keep the glyphs in the same place no matter what outline size is set.

See the web page at The FreeType2 Documentation Tutorial for more.

Any glyph based rendering calculations will not result in accurate kerning between adjacent glyphs. (see section Kerning)

See Also:
3.3.10 TTF_FontHeight,
3.3.11 TTF_FontAscent,
3.3.12 TTF_FontDescent,
3.3.13 TTF_FontLineSkip,
3.3.20 TTF_SizeText,
3.3.21 TTF_SizeUTF8,
3.3.22 TTF_SizeUNICODE,
3.3.18 TTF_GlyphIsProvided,
3.3.4 TTF_GetFontOutline

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.20 TTF_SizeText

int TTF_SizeText(TTF_Font *font, const char *text, int *w, int *h)

font
The loaded font to use to calculate the size of the string with.
text
The LATIN1 null terminated string to size up.
w
pointer to int in which to fill the text width, or NULL for no desired return value.
h
pointer to int in which to fill the text height, or NULL for no desired return value.

Calculate the resulting surface size of the LATIN1 encoded text rendered using font. No actual rendering is done, however correct kerning is done to get the actual width. The height returned in h is the same as you can get using 3.3.10 TTF_FontHeight.
NOTE: Passing a NULL font into this function will cause a segfault. NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: 0 on success with the ints pointed to by w and h set as appropriate, if they are not NULL. -1 is returned on errors, such as a glyph in the string not being found.

// get the width and height of a string as it would be rendered in a loaded font
//TTF_Font *font;
int w,h;
if(TTF_SizeText(font,"Hello World!",&w,&h)) {
    // perhaps print the current TTF_GetError(), the string can't be rendered...
} else {
    printf("width=%d height=%d\n",w,h);
}

See Also:
3.3.21 TTF_SizeUTF8,
3.3.22 TTF_SizeUNICODE,
3.4.1 TTF_RenderText_Solid,
3.4.5 TTF_RenderText_Shaded,
3.4.9 TTF_RenderText_Blended

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.21 TTF_SizeUTF8

int TTF_SizeUTF8(TTF_Font *font, const char *text, int *w, int *h)

font
The loaded font to use to calculate the size of the string with.
text
The UTF8 null terminated string to size up.
w
pointer to int in which to fill the text width, or NULL for no desired return value.
h
pointer to int in which to fill the text height, or NULL for no desired return value.

Calculate the resulting surface size of the UTF8 encoded text rendered using font. No actual rendering is done, however correct kerning is done to get the actual width. The height returned in h is the same as you can get using 3.3.10 TTF_FontHeight.
NOTE: Passing a NULL font into this function will cause a segfault. NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: 0 on success with the ints pointed to by w and h set as appropriate, if they are not NULL. -1 is returned on errors, such as a glyph in the string not being found.

Note that this example uses the same text as in the LATIN1 example, that is because plain ASCII is UTF8 compatible.
// get the width and height of a string as it would be rendered in a loaded font
//TTF_Font *font;
int w,h;
if(TTF_SizeUTF8(font,"Hello World!",&w,&h)) {
    // perhaps print the current TTF_GetError(), the string can't be rendered...
} else {
    printf("width=%d height=%d\n",w,h);
}

See Also:
3.3.20 TTF_SizeText,
3.3.22 TTF_SizeUNICODE,
3.4.2 TTF_RenderUTF8_Solid,
3.4.6 TTF_RenderUTF8_Shaded,
3.4.10 TTF_RenderUTF8_Blended

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.3.22 TTF_SizeUNICODE

int TTF_SizeUNICODE(TTF_Font *font, const Unit16 *text, int *w, int *h)

font
The loaded font to use to calculate the size of the string with.
text
The UNICODE null terminated string to size up.
w
pointer to int in which to fill the text width, or NULL for no desired return value.
h
pointer to int in which to fill the text height, or NULL for no desired return value.

Calculate the resulting surface size of the UNICODE encoded text rendered using font. No actual rendering is done, however correct kerning is done to get the actual width. The height returned in h is the same as you can get using 3.3.10 TTF_FontHeight.
NOTE: Passing a NULL font into this function will cause a segfault. NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: 0 on success with the ints pointed to by w and h set as appropriate, if they are not NULL. -1 is returned on errors, such as a glyph in the string not being found.

// get the width and height of a string as it would be rendered in a loaded font
//TTF_Font *font;
int w,h;
Uint16 text[]={'H','e','l','l','o',' ',
               'W','o','r','l','d','!'};
if(TTF_SizeUNICODE(font,text,&w,&h)) {
    // perhaps print the current TTF_GetError(), the string can't be rendered...
} else {
    printf("width=%d height=%d\n",w,h);
}

See Also:
3.3.20 TTF_SizeText,
3.3.21 TTF_SizeUTF8,
3.4.3 TTF_RenderUNICODE_Solid,
3.4.7 TTF_RenderUNICODE_Shaded,
3.4.11 TTF_RenderUNICODE_Blended

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4 Render

These functions render text using a TTF_Font.
There are three modes of rendering:

Solid
Quick and Dirty
Create an 8-bit palettized surface and render the given text at fast quality with the given font and color. The pixel value of 0 is the colorkey, giving a transparent background when blitted. Pixel and colormap value 1 is set to the text foreground color. This allows you to change the color without having to render the text again. Palette index 0 is of course not drawn when blitted to another surface, since it is the colorkey, and thus transparent, though its actual color is 255 minus each of the RGB components of the foreground color. This is the fastest rendering speed of all the rendering modes. This results in no box around the text, but the text is not as smooth. The resulting surface should blit faster than the Blended one. Use this mode for FPS and other fast changing updating text displays.
Shaded
Slow and Nice, but with a Solid Box
Create an 8-bit palettized surface and render the given text at high quality with the given font and colors. The 0 pixel value is background, while other pixels have varying degrees of the foreground color from the background color. This results in a box of the background color around the text in the foreground color. The text is antialiased. This will render slower than Solid, but in about the same time as Blended mode. The resulting surface should blit as fast as Solid, once it is made. Use this when you need nice text, and can live with a box.
Blended
Slow Slow Slow, but Ultra Nice over another image
Create a 32-bit ARGB surface and render the given text at high quality, using alpha blending to dither the font with the given color. This results in a surface with alpha transparency, so you don't have a solid colored box around the text. The text is antialiased. This will render slower than Solid, but in about the same time as Shaded mode. The resulting surface will blit slower than if you had used Solid or Shaded. Use this when you want high quality, and the text isn't changing too fast.

Solid
3.4.1 TTF_RenderText_Solid | Draw LATIN1 text in solid mode
3.4.2 TTF_RenderUTF8_Solid | Draw UTF8 text in solid mode
3.4.3 TTF_RenderUNICODE_Solid | Draw UNICODE text in solid mode
3.4.4 TTF_RenderGlyph_Solid | Draw a UNICODE glyph in solid mode
Shaded
3.4.5 TTF_RenderText_Shaded | Draw LATIN1 text in shaded mode
3.4.6 TTF_RenderUTF8_Shaded | Draw UTF8 text in shaded mode
3.4.7 TTF_RenderUNICODE_Shaded | Draw UNICODE text in shaded mode
3.4.8 TTF_RenderGlyph_Shaded | Draw a UNICODE glyph in shaded mode
Blended
3.4.9 TTF_RenderText_Blended | Draw LATIN1 text in blended mode
3.4.10 TTF_RenderUTF8_Blended | Draw UTF8 text in blended mode
3.4.11 TTF_RenderUNICODE_Blended | Draw UNICODE text in blended mode
3.4.12 TTF_RenderGlyph_Blended | Draw a UNICODE glyph in blended mode

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.1 TTF_RenderText_Solid

SDL_Surface *TTF_RenderText_Solid(TTF_Font *font, const char *text, SDL_Color fg)

font
Font to render the text with. A NULL pointer is not checked.
text
The LATIN1 null terminated string to render.
fg
The color to render the text in. This becomes colormap index 1.

Render the LATIN1 encoded text using font with fg color onto a new surface, using the Solid mode (see section Solid). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

// Render some text in solid black to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0};
SDL_Surface *text_surface;
if(!(text_surface=TTF_RenderText_Solid(font,"Hello World!",color))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.20 TTF_SizeText,
3.4.2 TTF_RenderUTF8_Solid,
3.4.3 TTF_RenderUNICODE_Solid,
3.4.4 TTF_RenderGlyph_Solid,
3.4.5 TTF_RenderText_Shaded,
3.4.9 TTF_RenderText_Blended

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.2 TTF_RenderUTF8_Solid

SDL_Surface *TTF_RenderUTF8_Solid(TTF_Font *font, const char *text, SDL_Color fg)

font
Font to render the text with. A NULL pointer is not checked.
text
The UTF8 null terminated string to render.
fg
The color to render the text in. This becomes colormap index 1.

Render the UTF8 encoded text using font with fg color onto a new surface, using the Solid mode (see section Solid). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

Note that this example uses the same text as in the LATIN1 example, that is because plain ASCII is UTF8 compatible.
// Render some UTF8 text in solid black to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0};
SDL_Surface *text_surface;
if(!(text_surface=TTF_RenderUTF8_Solid(font,"Hello World!",color))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.21 TTF_SizeUTF8,
3.4.1 TTF_RenderText_Solid,
3.4.3 TTF_RenderUNICODE_Solid,
3.4.4 TTF_RenderGlyph_Solid,
3.4.6 TTF_RenderUTF8_Shaded,
3.4.10 TTF_RenderUTF8_Blended

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.3 TTF_RenderUNICODE_Solid

SDL_Surface *TTF_RenderUNICODE_Solid(TTF_Font *font, const Uint16 *text, SDL_Color fg)

font
Font to render the text with. A NULL pointer is not checked.
text
The UNICODE null terminated string to render.
fg
The color to render the text in. This becomes colormap index 1.

Render the UNICODE encoded text using font with fg color onto a new surface, using the Solid mode (see section Solid). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

// Render some UNICODE text in solid black to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0};
SDL_Surface *text_surface;
Uint16 text[]={'H','e','l','l','o',' ',
               'W','o','r','l','d','!'};
if(!(text_surface=TTF_RenderUNICODE_Solid(font,text,color))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.22 TTF_SizeUNICODE,
3.4.1 TTF_RenderText_Solid,
3.4.2 TTF_RenderUTF8_Solid,
3.4.4 TTF_RenderGlyph_Solid,
3.4.7 TTF_RenderUNICODE_Shaded,
3.4.11 TTF_RenderUNICODE_Blended

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.4 TTF_RenderGlyph_Solid

SDL_Surface *TTF_RenderGlyph_Solid(TTF_Font *font, Uint16 ch, SDL_Color fg)

font
Font to render the glyph with. A NULL pointer is not checked.
text
The UNICODE character to render.
fg
The color to render the glyph in. This becomes colormap index 1.

Render the glyph for the UNICODE ch using font with fg color onto a new surface, using the Solid mode (see section Solid). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors, such as when the glyph not available in the font.

// Render and cache all printable ASCII characters in solid black
//SDL_Surface *screen;
SDL_Color color={0,0,0};
SDL_Surface *glyph_cache[128-20];
Uint16 ch;
for(ch=20; ch<128; ++ch)
    glyph_cache[ch-20]=TTF_RenderGlyph_Solid(font,ch,color);
Combined with a cache of the glyph metrics (minx, miny, and advance), you might make a fast text rendering routine that prints directly to the screen, but with inaccurate kerning. (see section Kerning)

See Also:
3.4.8 TTF_RenderGlyph_Shaded,
3.4.12 TTF_RenderGlyph_Blended,
3.4.1 TTF_RenderText_Solid,
3.4.2 TTF_RenderUTF8_Solid,
3.4.4 TTF_RenderGlyph_Solid,
3.3.19 TTF_GlyphMetrics

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.5 TTF_RenderText_Shaded

SDL_Surface *TTF_RenderText_Shaded(TTF_Font *font, const char *text, SDL_Color fg, SDL_Color bg)

font
Font to render the text with. A NULL pointer is not checked.
text
The LATIN1 null terminated string to render.
fg
The color to render the text in. This becomes colormap index 1.
bg
The color to render the background box in. This becomes colormap index 0.

Render the LATIN1 encoded text using font with fg color onto a new surface filled with the bg color, using the Shaded mode (see section Shaded). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

// Render some text in shaded black on white to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0}, bgcolor={0xff,0xff,0xff};
SDL_Surface *text_surface;
if(!(text_surface=TTF_RenderText_Shaded(font,"Hello World!",color,bgcolor))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.20 TTF_SizeText,
3.4.6 TTF_RenderUTF8_Shaded,
3.4.7 TTF_RenderUNICODE_Shaded,
3.4.8 TTF_RenderGlyph_Shaded,
3.4.1 TTF_RenderText_Solid,
3.4.9 TTF_RenderText_Blended

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.6 TTF_RenderUTF8_Shaded

SDL_Surface *TTF_RenderUTF8_Shaded(TTF_Font *font, const char *text, SDL_Color fg, SDL_Color bg)

font
Font to render the text with. A NULL pointer is not checked.
text
The UTF8 null terminated string to render.
fg
The color to render the text in. This becomes colormap index 1.
bg
The color to render the background box in. This becomes colormap index 0.

Render the UTF8 encoded text using font with fg color onto a new surface filled with the bg color, using the Shaded mode (see section Shaded). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

Note that this example uses the same text as in the LATIN1 example, that is because plain ASCII is UTF8 compatible.
// Render some UTF8 text in shaded black on white to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0}, bgcolor={0xff,0xff,0xff};
SDL_Surface *text_surface;
if(!(text_surface=TTF_RenderUTF8_Shaded(font,"Hello World!",color,bgcolor))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.21 TTF_SizeUTF8,
3.4.5 TTF_RenderText_Shaded,
3.4.7 TTF_RenderUNICODE_Shaded,
3.4.8 TTF_RenderGlyph_Shaded,
3.4.2 TTF_RenderUTF8_Solid,
3.4.10 TTF_RenderUTF8_Blended

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.7 TTF_RenderUNICODE_Shaded

SDL_Surface *TTF_RenderUNICODE_Shaded(TTF_Font *font, const Uint16 *text, SDL_Color fg, SDL_Color bg)

font
Font to render the text with. A NULL pointer is not checked.
text
The UNICODE null terminated string to render.
fg
The color to render the text in. This becomes colormap index 1.
bg
The color to render the background box in. This becomes colormap index 0.

Render the UNICODE encoded text using font with fg color onto a new surface filled with the bg color, using the Shaded mode (see section Shaded). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

// Render some UNICODE text in shaded black on white to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0}, bgcolor={0xff,0xff,0xff};
SDL_Surface *text_surface;
Uint16 text[]={'H','e','l','l','o',' ',
               'W','o','r','l','d','!'};
if(!(text_surface=TTF_RenderUNICODE_Shaded(font,text,color,bgcolor))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.22 TTF_SizeUNICODE,
3.4.5 TTF_RenderText_Shaded,
3.4.6 TTF_RenderUTF8_Shaded,
3.4.8 TTF_RenderGlyph_Shaded,
3.4.3 TTF_RenderUNICODE_Solid,
3.4.11 TTF_RenderUNICODE_Blended

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.8 TTF_RenderGlyph_Shaded

SDL_Surface *TTF_RenderGlyph_Shaded(TTF_Font *font, Uint16 ch, SDL_Color fg, SDL_Color bg)

font
Font to render the glyph with. A NULL pointer is not checked.
text
The UNICODE character to render.
fg
The color to render the glyph in. This becomes colormap index 1.
bg
The color to render the background box in. This becomes colormap index 0.

Render the glyph for the UNICODE ch using font with fg color onto a new surface filled with the bg color, using the Shaded mode (see section Shaded). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors, such as when the glyph not available in the font.

// Render and cache all printable ASCII characters in shaded black on white
//SDL_Surface *screen;
SDL_Color color={0,0,0}, bgcolor={0xff,0xff,0xff};
SDL_Surface *glyph_cache[128-20];
Uint16 ch;
for(ch=20; ch<128; ++ch)
    glyph_cache[ch-20]=TTF_RenderGlyph_Shaded(font,ch,color,bgcolor);
Combined with a cache of the glyph metrics (minx, miny, and advance), you might make a fast text rendering routine that prints directly to the screen, but with inaccurate kerning. (see section Kerning)

See Also:
3.4.4 TTF_RenderGlyph_Solid,
3.4.12 TTF_RenderGlyph_Blended,
3.4.5 TTF_RenderText_Shaded,
3.4.6 TTF_RenderUTF8_Shaded,
3.4.8 TTF_RenderGlyph_Shaded,
3.3.19 TTF_GlyphMetrics

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.9 TTF_RenderText_Blended

SDL_Surface *TTF_RenderText_Blended(TTF_Font *font, const char *text, SDL_Color fg)

font
Font to render the text with. A NULL pointer is not checked.
text
The LATIN1 null terminated string to render.
fg
The color to render the text in. Pixels are blended between transparent and this color to draw the antialiased glyphs.

Render the LATIN1 encoded text using font with fg color onto a new surface, using the Blended mode (see section Blended). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

// Render some text in blended black to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0};
SDL_Surface *text_surface;
if(!(text_surface=TTF_RenderText_Blended(font,"Hello World!",color))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.20 TTF_SizeText,
3.4.10 TTF_RenderUTF8_Blended,
3.4.11 TTF_RenderUNICODE_Blended,
3.4.12 TTF_RenderGlyph_Blended,
3.4.1 TTF_RenderText_Solid,
3.4.5 TTF_RenderText_Shaded

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.10 TTF_RenderUTF8_Blended

SDL_Surface *TTF_RenderUTF8_Blended(TTF_Font *font, const char *text, SDL_Color fg)

font
Font to render the text with. A NULL pointer is not checked.
text
The UTF8 null terminated string to render.
fg
The color to render the text in. Pixels are blended between transparent and this color to draw the antialiased glyphs.

Render the UTF8 encoded text using font with fg color onto a new surface, using the Blended mode (see section Blended). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

Note that this example uses the same text as in the LATIN1 example, that is because plain ASCII is UTF8 compatible.
// Render some UTF8 text in blended black to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0};
SDL_Surface *text_surface;
if(!(text_surface=TTF_RenderUTF8_Blended(font,"Hello World!",color))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.21 TTF_SizeUTF8,
3.4.9 TTF_RenderText_Blended,
3.4.11 TTF_RenderUNICODE_Blended,
3.4.12 TTF_RenderGlyph_Blended,
3.4.2 TTF_RenderUTF8_Solid,
3.4.6 TTF_RenderUTF8_Shaded

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.11 TTF_RenderUNICODE_Blended

SDL_Surface *TTF_RenderUNICODE_Blended(TTF_Font *font, const Uint16 *text, SDL_Color fg)

font
Font to render the text with. A NULL pointer is not checked.
text
The UNICODE null terminated string to render.
fg
The color to render the text in. Pixels are blended between transparent and this color to draw the antialiased glyphs.

Render the UNICODE encoded text using font with fg color onto a new surface, using the Blended mode (see section Blended). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

// Render some UNICODE text in blended black to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0};
SDL_Surface *text_surface;
Uint16 text[]={'H','e','l','l','o',' ',
               'W','o','r','l','d','!'};
if(!(text_surface=TTF_RenderUNICODE_Blended(font,text,color))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.22 TTF_SizeUNICODE,
3.4.9 TTF_RenderText_Blended,
3.4.10 TTF_RenderUTF8_Blended,
3.4.12 TTF_RenderGlyph_Blended,
3.4.3 TTF_RenderUNICODE_Solid,
3.4.7 TTF_RenderUNICODE_Shaded

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

3.4.12 TTF_RenderGlyph_Blended

SDL_Surface *TTF_RenderGlyph_Blended(TTF_Font *font, Uint16 ch, SDL_Color fg)

font
Font to render the glyph with. A NULL pointer is not checked.
text
The UNICODE character to render.
fg
The color to render the glyph in. Pixels are blended between transparent and this color to draw the antialiased glyph.

Render the glyph for the UNICODE ch using font with fg color onto a new surface, using the Blended mode (see section Blended). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors, such as when the glyph not available in the font.

// Render and cache all printable ASCII characters in blended black
//SDL_Surface *screen;
SDL_Color color={0,0,0};
SDL_Surface *glyph_cache[128-20];
Uint16 ch;
for(ch=20; ch<128; ++ch)
    glyph_cache[ch-20]=TTF_RenderGlyph_Blended(font,ch,color);
Combined with a cache of the glyph metrics (minx, miny, and advance), you might make a fast text rendering routine that prints directly to the screen, but with inaccurate kerning. (see section Kerning)

See Also:
3.4.4 TTF_RenderGlyph_Solid,
3.4.8 TTF_RenderGlyph_Shaded,
3.4.9 TTF_RenderText_Blended,
3.4.10 TTF_RenderUTF8_Blended,
3.4.12 TTF_RenderGlyph_Blended,
3.3.19 TTF_GlyphMetrics

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4. Types

These types are defined and used by the SDL_ttf API.

4.1 TTF_Font The opaque holder of a loaded font

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

4.1 TTF_Font

typedef struct _TTF_Font TTF_Font;

The opaque holder of a loaded font. You should always be using a pointer of this type, as in TTF_Font*, and not just plain TTF_Font. This stores the font data in a struct that is exposed only by using the API functions to get information. You should not try to access the struct data directly, since the struct may change in different versions of the API, and thus your program would be unreliable.

See Also:
3.2 Management

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

5. Defines

TTF_MAJOR_VERSION
2
SDL_ttf library major number at compilation time.
TTF_MINOR_VERSION
0
SDL_ttf library minor number at compilation time.
TTF_PATCHLEVEL
10
SDL_ttf library patch level at compilation time.
UNICODE_BOM_NATIVE
0xFEFF
This allows you to switch byte-order of UNICODE text data to native order, meaning the mode of your CPU. This is meant to be used in a UNICODE string that you are using with the SDL_ttf API.
UNICODE_BOM_SWAPPED
0xFFFE
This allows you to switch byte-order of UNICODE text data to swapped order, meaning the reversed mode of your CPU. So if your CPU is LSB, then the data will be interpretted as MSB. This is meant to be used in a UNICODE string that you are using with the SDL_ttf API.
TTF_STYLE_NORMAL
0x00
Used to indicate regular, normal, plain rendering style.
TTF_STYLE_BOLD
0x01
Used to indicate bold rendering style. This is used in a bitmask along with other styles.
TTF_STYLE_ITALIC
0x02
Used to indicate italicized rendering style. This is used in a bitmask along with other styles.
TTF_STYLE_UNDERLINE
0x04
Used to indicate underlined rendering style. This is used in a bitmask along with other styles.
TTF_STYLE_STRIKETHROUGH
0x08
Used to indicate strikethrough rendering style. This is used in a bitmask along with other styles.
TTF_HINTING_NORMAL
0
Used to indicate set hinting type to normal.
This corresponds to the default hinting algorithm, optimized for standard gray-level rendering
TTF_HINTING_LIGHT
0
Used to indicate set hinting type to light.
A lighter hinting algorithm for non-monochrome modes. Many generated glyphs are more fuzzy but better resemble its original shape. A bit like rendering on Mac OS X.
TTF_HINTING_MONO
0
Used to indicate set hinting type to monochrome.
Strong hinting algorithm that should only be used for monochrome output. The result is probably unpleasant if the glyph is rendered in non-monochrome modes.
TTF_HINTING_NONE
0
Used to indicate set hinting type to none.
No hinting is used so the font may become very blurry or messy at smaller sizes.

See Also:
6. Glossary,

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

6. Glossary

Byte Order This all has to do with how data larger than a byte is actually stored in memory. The CPU expects 16bit and 32bit, and larger, data to be ordered in one of the two ways listed below. SDL has macros which you can use to detemine which endianness your program will be using.

Big-Endian(MSB) means the most significant byte comes first in storage. Sparc and Motorola 68k based chips are MSB ordered.
(SDL defines this as SDL_BYTEORDER==SDL_BIG_ENDIAN)

Little-Endian(LSB) is stored in the opposite order, with the least significant byte first in memory. Intel and AMD are two LSB machines.
(SDL defines this as SDL_BYTEORDER==SDL_LIL_ENDIAN)

LATIN1 Latin-1 is an extension of ASCII, where ASCII only defines characters 0 through 127. Latin-1 continues and adds more common international symbols to define through character 255.

ISO 8859-1 (Latin-1) Unicode Table (pdf)

Hinting Font hinting is the use of mathematical instructions to adjust the display of an outline font so that it lines up with a rasterized grid. At small screen sizes, with or without antialiasing, hinting is critical for producing a clear, legible text for human readers.

Kerning Kerning is the process of spacing adjacent characters apart depending on the actual two adjacent characters. This allows some characters to be closer to each other than others. When kerning is not used, such as when using the glyph metrics advance value, the characters will be spaced out at a constant size that accomodates all pairs of adjacent characters. This would be the maximum space between characters needed. There's currently no method to retrieve the kerning for a pair of characters from SDL_ttf, However correct kerning will be applied when a string of text is rendered instead of individual glyphs.

[ < ] [ > ] [ << ] [ Up ] [ >> ] [Top] [Contents] [Index] [ ? ]

Index

Jump to: A B H K L M R S T U

 | Index Entry | Section
A |  |
 | ASCII | 6. Glossary
B |  |
 | Big-Endian | 6. Glossary
 | Blended | 3.4 Render
 | Byte Order | 6. Glossary
H |  |
 | Hinting | 6. Glossary
K |  |
 | Kerning | 6. Glossary
L |  |
 | LATIN1 | 6. Glossary
 | Little-Endian | 6. Glossary
 | LSB | 6. Glossary
M |  |
 | MSB | 6. Glossary
R |  |
 | README | 1. Overview
S |  |
 | sdl-config | 2.2 Compiling
 | SDL_TTF_MAJOR_VERSION | 5. Defines
 | SDL_TTF_MINOR_VERSION | 5. Defines
 | SDL_TTF_PATCHLEVEL | 5. Defines
 | SDL_TTF_VERSION | 3.1.1 TTF_Linked_Version
 | Shaded | 3.4 Render
 | Solid | 3.4 Render
T |  |
 | TTF_ByteSwappedUNICODE | 3.3.1 TTF_ByteSwappedUNICODE
 | TTF_CloseFont | 3.2.5 TTF_CloseFont
 | TTF_Font | 3.2 Management
 | TTF_Font | 3.3 Attributes
 | TTF_Font | 3.4 Render
 | TTF_Font | 4.1 TTF_Font
 | TTF_FontAscent | 3.3.11 TTF_FontAscent
 | TTF_FontDescent | 3.3.12 TTF_FontDescent
 | TTF_FontFaceFamilyName | 3.3.16 TTF_FontFaceFamilyName
 | TTF_FontFaceIsFixedWidth | 3.3.15 TTF_FontFaceIsFixedWidth
 | TTF_FontFaces | 3.3.14 TTF_FontFaces
 | TTF_FontFaceStyleName | 3.3.17 TTF_FontFaceStyleName
 | TTF_FontHeight | 3.3.10 TTF_FontHeight
 | TTF_FontLineSkip | 3.3.13 TTF_FontLineSkip
 | TTF_GetError | 3.1.6 TTF_GetError
 | TTF_GetFontHinting | 3.3.6 TTF_GetFontHinting
 | TTF_GetFontKerning | 3.3.8 TTF_GetFontKerning
 | TTF_GetFontOutline | 3.3.4 TTF_GetFontOutline
 | TTF_GetFontStyle | 3.3.2 TTF_GetFontStyle
 | TTF_GlyphIsProvided | 3.3.18 TTF_GlyphIsProvided
 | TTF_GlyphMetrics | 3.3.19 TTF_GlyphMetrics
 | TTF_HINTING_LIGHT | 5. Defines
 | TTF_HINTING_MONO | 5. Defines
 | TTF_HINTING_NONE | 5. Defines
 | TTF_HINTING_NORMAL | 5. Defines
 | TTF_Init | 3.1.2 TTF_Init
 | TTF_Linked_Version | 3.1.1 TTF_Linked_Version
 | TTF_OpenFont | 3.2.1 TTF_OpenFont
 | TTF_OpenFontIndex | 3.2.3 TTF_OpenFontIndex
 | TTF_OpenFontIndexRW | 3.2.4 TTF_OpenFontIndexRW
 | TTF_OpenFontRW | 3.2.2 TTF_OpenFontRW
 | TTF_Quit | 3.1.4 TTF_Quit
 | TTF_RenderGlyph_Blended | 3.4.12 TTF_RenderGlyph_Blended
 | TTF_RenderGlyph_Shaded | 3.4.8 TTF_RenderGlyph_Shaded
 | TTF_RenderGlyph_Solid | 3.4.4 TTF_RenderGlyph_Solid
 | TTF_RenderText_Blended | 3.4.9 TTF_RenderText_Blended
 | TTF_RenderText_Shaded | 3.4.5 TTF_RenderText_Shaded
 | TTF_RenderText_Solid | 3.4.1 TTF_RenderText_Solid
 | TTF_RenderUNICODE_Blended | 3.4.11 TTF_RenderUNICODE_Blended
 | TTF_RenderUNICODE_Shaded | 3.4.7 TTF_RenderUNICODE_Shaded
 | TTF_RenderUNICODE_Solid | 3.4.3 TTF_RenderUNICODE_Solid
 | TTF_RenderUTF8_Blended | 3.4.10 TTF_RenderUTF8_Blended
 | TTF_RenderUTF8_Shaded | 3.4.6 TTF_RenderUTF8_Shaded
 | TTF_RenderUTF8_Solid | 3.4.2 TTF_RenderUTF8_Solid
 | TTF_SetError | 3.1.5 TTF_SetError
 | TTF_SetFontHinting | 3.3.7 TTF_SetFontHinting
 | TTF_SetFontKerning | 3.3.9 TTF_SetFontKerning
 | TTF_SetFontOutline | 3.3.5 TTF_SetFontOutline
 | TTF_SetFontStyle | 3.3.3 TTF_SetFontStyle
 | TTF_SizeText | 3.3.20 TTF_SizeText
 | TTF_SizeUNICODE | 3.3.22 TTF_SizeUNICODE
 | TTF_SizeUTF8 | 3.3.21 TTF_SizeUTF8
 | TTF_STYLE_BOLD | 5. Defines
 | TTF_STYLE_ITALIC | 5. Defines
 | TTF_STYLE_NORMAL | 5. Defines
 | TTF_STYLE_STRIKETHROUGH | 5. Defines
 | TTF_STYLE_UNDERLINE | 5. Defines
 | TTF_WasInit | 3.1.3 TTF_WasInit
U |  |
 | UNICODE_BOM_NATIVE | 5. Defines
 | UNICODE_BOM_SWAPPED | 5. Defines

Jump to: A B H K L M R S T U

[Top] [Contents] [Index] [ ? ]

Table of Contents

    1. Overview
    2. Getting Started
      2.1 Includes
      2.2 Compiling
    3. Functions
      3.1 General
        3.1.1 TTF_Linked_Version
        3.1.2 TTF_Init
        3.1.3 TTF_WasInit
        3.1.4 TTF_Quit
        3.1.5 TTF_SetError
        3.1.6 TTF_GetError
      3.2 Management
        3.2.1 TTF_OpenFont
        3.2.2 TTF_OpenFontRW
        3.2.3 TTF_OpenFontIndex
        3.2.4 TTF_OpenFontIndexRW
        3.2.5 TTF_CloseFont
      3.3 Attributes
        3.3.1 TTF_ByteSwappedUNICODE
        3.3.2 TTF_GetFontStyle
        3.3.3 TTF_SetFontStyle
        3.3.4 TTF_GetFontOutline
        3.3.5 TTF_SetFontOutline
        3.3.6 TTF_GetFontHinting
        3.3.7 TTF_SetFontHinting
        3.3.8 TTF_GetFontKerning
        3.3.9 TTF_SetFontKerning
        3.3.10 TTF_FontHeight
        3.3.11 TTF_FontAscent
        3.3.12 TTF_FontDescent
        3.3.13 TTF_FontLineSkip
        3.3.14 TTF_FontFaces
        3.3.15 TTF_FontFaceIsFixedWidth
        3.3.16 TTF_FontFaceFamilyName
        3.3.17 TTF_FontFaceStyleName
        3.3.18 TTF_GlyphIsProvided
        3.3.19 TTF_GlyphMetrics
        3.3.20 TTF_SizeText
        3.3.21 TTF_SizeUTF8
        3.3.22 TTF_SizeUNICODE
      3.4 Render
        3.4.1 TTF_RenderText_Solid
        3.4.2 TTF_RenderUTF8_Solid
        3.4.3 TTF_RenderUNICODE_Solid
        3.4.4 TTF_RenderGlyph_Solid
        3.4.5 TTF_RenderText_Shaded
        3.4.6 TTF_RenderUTF8_Shaded
        3.4.7 TTF_RenderUNICODE_Shaded
        3.4.8 TTF_RenderGlyph_Shaded
        3.4.9 TTF_RenderText_Blended
        3.4.10 TTF_RenderUTF8_Blended
        3.4.11 TTF_RenderUNICODE_Blended
        3.4.12 TTF_RenderGlyph_Blended
    4. Types
      4.1 TTF_Font
    5. Defines
    6. Glossary
    Index
[Top] [Contents] [Index] [ ? ]

Short Table of Contents

1. Overview
2. Getting Started
3. Functions
4. Types
5. Defines
6. Glossary
Index
[Top] [Contents] [Index] [ ? ]

About this document

This document was generated on November, 13 2009 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated on November, 13 2009 using texi2html


SDL_image 1.2.8: SDL_image 1.2.8

SDL_image 1.2.8

1. Overview The README from the SDL_image distribution

2. Getting Started Using SDL_image

3. Functions | Functions supported by the SDL_image API
4. Defines | Defined values/macros in the SDL_image API

Index Index of selected words

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: Overview

1. Overview

A Little Bit About Me

I am currently, as I write this document, a programmer for Raytheon. There I do all sorts of communications, network, GUI, and other general programming tasks in C/C++ on the Solaris, Linux, and Windows Operating Systems.

Feel free to contact me: JonathanCAtkins@gmail.com

I am also usually on IRC at irc.freenode.net in the #SDL channel as LIM

Why is this for you?

Images provide the basic visual building blocks for any user interface. Colors and fun shapes are the stuff that we as kids looked at for hours at a time while trying to shoot down big aliens and rescue pixelated princesses. Now it's our turn to make the images that others will remember later in life perhaps. Now how do we get this dang images into our SDL programs, and be flexible in the handling of the images so that we don't even have to worry about what various formats they may be in? This is where SDLimage makes all of our lives easier. This document doesn't help you make artwork, but it will give you the functional knowledge on how to get that art into your game. Now go forth and make your Stick Figure of Justice, someone else might fill in for your lack of artistry, at least you won't have to make much of an effort to include the new and better art into your code.

This is the README, updated by me for accuracy, in the SDL_image source archive.

SDL_image 1.2

The latest version of this library is available from:
SDL_image Homepage

This is a simple library to load images of various formats as SDL surfaces.
This library supports ICO(Icon)/CUR(Cursor)/BMP, PNM (PPM/PGM/PBM), XPM,
LBM(IFF ILBM), PCX, GIF, JPEG, PNG, TGA, TIFF, and XV thumbnail formats.

API:
#include "SDL_image.h"

    SDL_Surface *IMG_Load(const char *file);
or
    SDL_Surface *IMG_Load_RW(SDL_RWops *src, int freesrc);
or
    SDL_Surface *IMG_LoadTyped_RW(SDL_RWops *src, int freesrc, char *type);

where type is a string specifying the format (i.e. "PNG" or "pcx").
Note that IMG_Load_RW cannot load TGA images.

To create a surface from an XPM image included in C source, use:

    SDL_Surface *IMG_ReadXPMFromArray(char **xpm);

An example program 'showimage' is included, with source in showimage.c

JPEG support requires the JPEG library:
    IJG Homepage
PNG support requires the PNG library:
    PNG Homepage
  and the Zlib library:
    Zlib Homepage
TIFF support requires the TIFF library:
    SGI TIFF FTP Site

If you have these libraries installed in non-standard places, you can
try adding those paths to the configure script, e.g.
sh ./configure CPPFLAGS="-I/somewhere/include" LDFLAGS="-L/somewhere/lib"
If this works, you may need to add /somewhere/lib to your LD_LIBRARY_PATH
so shared library loading works correctly.

This library is under the GNU Library General Public License, see the file
"COPYING" for details.  Certain image loaders may be under a different
license, see the individual image loader source files for details.

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: Getting Started

2. Getting Started

This assumes you have gotten SDL_image and installed it on your system. SDL_image has an README document in the source distribution to help you get it compiled and installed. Well it at least points you to locations for the source code of some of the image libraries SDL_image can use. Most of the other image formats are builtin to SDL_image.

Generally, in UNIX-like environments, installation consists of:

./configure
make
make install

SDL_image supports loading and decoding images from the following formats:

TGA
TrueVision Targa (MUST have .tga)
BMP
Windows Bitmap(.bmp)
PNM
Portable Anymap (.pnm)
.pbm = Portable BitMap (mono)
.pgm = Portable GreyMap (256 greys)
.ppm = Portable PixMap (full color)
XPM
X11 Pixmap (.xpm) can be #included directly in code
This is NOT the same as XBM(X11 Bitmap) format, which is for monocolor images.
XCF
GIMP native (.xcf) (XCF = eXperimental Computing Facility?)
This format is always changing, and since there's no library supplied by the GIMP project to load XCF, the loader may frequently fail to load much of any image from an XCF file. It's better to load this in GIMP and convert to a better supported image format.
PCX
ZSoft IBM PC Paintbrush (.pcx)
GIF
CompuServe Graphics Interchange Format (.gif)
JPG
Joint Photographic Experts Group JFIF format (.jpg or .jpeg)
TIF
Tagged Image File Format (.tif or .tiff)
LBM
Interleaved Bitmap (.lbm or .iff) FORM : ILBM or PBM(packed bitmap)
HAM6, HAM8, and 24bit types are not supported.
PNG
Portable Network Graphics (.png)

You may also want to look at some demonstration code which may be downloaded from:
http://www.jonatkins.org/SDL_image/

2.1 Includes | The include files to use for SDL_image
2.2 Compiling | Using the SDL_image library and header file.

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: Includes

2.1 Includes

To use SDL_image functions in a C/C++ source code file, you must use the SDL_image.h include file:

#include "SDL_image.h"

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: Compiling

2.2 Compiling

To link with SDL_image you should use sdl-config to get the required SDL compilation options. After that, compiling with SDL_image is quite easy.
Note: Some systems may not have the SDL_image library and include file in the same place as the SDL library and includes are located, in that case you will need to add more -I and -L paths to these command lines.

Simple Example for compiling an object file:

cc -c `sdl-config --cflags` mysource.c

Simple Example for compiling an object file:

cc -o myprogram mysource.o `sdl-config --libs` -lSDL_image

Now myprogram is ready to run.

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: Functions

3. Functions

These are the functions in the SDL_image API.

3.1 General | Versioning, Initialization and Cleanup
3.2 Loading | From Image Data to SDL_Surface
3.3 Info | Image Type Detection
3.4 Errors | Error Handling

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: General

3.1 General

These functions query, initialize, and cleanup the SDL_image library.

3.1.1 IMG_Linked_Version | Get version number
3.1.2 IMG_Init | Initialize SDL_image
3.1.3 IMG_Quit | Cleanup SDL_image

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_Linked_Version

3.1.1 IMG_Linked_Version

const SDL_version *IMG_Linked_Version()
void SDL_IMAGE_VERSION(SDL_version *compile_version)

This works similar to SDL_Linked_Version and SDL_VERSION.
Using these you can compare the runtime version to the version that you compiled with.
These functions/macros do not require any library initialization calls before using them.

SDL_version compile_version;
const SDL_version *link_version=IMG_Linked_Version();
SDL_IMAGE_VERSION(&compile_version);
printf("compiled with SDL_image version: %d.%d.%d\n",
        compile_version.major,
        compile_version.minor,
        compile_version.patch);
printf("running with SDL_image version: %d.%d.%d\n",
        link_version->major,
        link_version->minor,
        link_version->patch);

See Also:
3.1.2 IMG_Init

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_Init

3.1.2 IMG_Init

int IMG_Init(int flags)

flags
bitwise OR'd set of image formats to support by loading a library now. The values you may OR together to pass in are:
IMG_INIT_JPG
IMG_INIT_PNG
IMG_INIT_TIF

Initialize by loading support as indicated by the flags, or at least return success if support is already loaded. You may call this multiple times, which will actually require you to call IMG_Quit just once to clean up. You may call this function with a 0 to retrieve whether support was built-in or not loaded yet.
Note: to load JPG, PNG, and/or TIF images you can call IMG_Init with the right IMG_INIT_* flags OR'd together before you program gets busy, to prevent a later hiccup while it loads the library, and to check that you do have the support that you need before you try and use it.
Note: No initialization is needed nor performed when using the IMG_isJPG, IMG_isPNG, and IMG_isTIF functions.
Note: this function does not always set the error string, so do not depend on IMG_GetError being meaningful all the time.

Returns: a bitmask of all the currently initted image loaders.

// load support for the JPG and PNG image formats
int flags=IMG_INIT_JPG|IMG_INIT_PNG;
int initted=IMG_Init(flags);
if(initted&flags != flags) {
    printf("IMG_Init: Failed to init required jpg and png support!\n");
    printf("IMG_Init: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.3 IMG_Quit

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_Quit

3.1.3 IMG_Quit

void IMG_Quit()

This function cleans up all dynamically loaded library handles, freeing memory. If support is required again it will be initialized again, either by IMG_Init or loading an image with dynamic support required. You may call this function when IMG_Load functions are no longer needed for the JPG, PNG, and TIF image formats. You only need to call this function once, no matter how many times IMG_Init was called.

// unload the dynamically loaded image libraries
IMG_Quit();

See Also:
3.1.2 IMG_Init

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: Loading

3.2 Loading

These functions create an SDL_Surface from image data either from a file, or SDL_RWop, or from an array of data in memory.

Automagic Loading
3.2.1 IMG_Load | Load from a file
3.2.2 IMG_Load_RW | Load using a SDL_RWop
3.2.3 IMG_LoadTyped_RW | Load more format specifically with a SDL_RWop
Specific Loaders
3.2.6 IMG_LoadBMP_RW | Load BMP using a SDL_RWop
3.2.4 IMG_LoadCUR_RW | Load CUR using a SDL_RWop
3.2.11 IMG_LoadGIF_RW | Load GIF using a SDL_RWop
3.2.5 IMG_LoadICO_RW | Load ICO using a SDL_RWop
3.2.12 IMG_LoadJPG_RW | Load JPG using a SDL_RWop
3.2.16 IMG_LoadLBM_RW | Load LBM using a SDL_RWop
3.2.10 IMG_LoadPCX_RW | Load PCX using a SDL_RWop
3.2.14 IMG_LoadPNG_RW | Load PNG using a SDL_RWop
3.2.7 IMG_LoadPNM_RW | Load PNM using a SDL_RWop
3.2.15 IMG_LoadTGA_RW | Load TGA using a SDL_RWop
3.2.13 IMG_LoadTIF_RW | Load TIF using a SDL_RWop
3.2.9 IMG_LoadXCF_RW | Load XCF using a SDL_RWop
3.2.8 IMG_LoadXPM_RW | Load XPM using a SDL_RWop
3.2.17 IMG_LoadXV_RW | Load XV using a SDL_RWop
Array Loaders
3.2.18 IMG_ReadXPMFromArray Load XPM from compiled XPM data

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_Load

3.2.1 IMG_Load

SDL_Surface *IMG_Load(const char *file)

file
Image file name to load a surface from.

Load file for use as an image in a new surface. This actually calls IMG_LoadTyped_RW, with the file extension used as the type string. This can load all supported image files, including TGA as long as the filename ends with ".tga". It is best to call this outside of event loops, and rather keep the loaded images around until you are really done with them, as disk speed and image conversion to a surface is not that speedy. Don't forget to SDL_FreeSurface the returned surface pointer when you are through with it.
Note: If the image format loader requires initialization, it will attempt to do that the first time it is needed if you have not already called IMG_Init to load support for your image format.
Note: If the image format supports a transparent pixel, SDL_image will set the colorkey for the surface. You can enable RLE acceleration on the surface afterwards by calling:
SDL_SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, such as no support built for the image, or a file reading error.

// load sample.png into image
SDL_Surface *image;
image=IMG_Load("sample.png");
if(!image) {
    printf("IMG_Load: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.2 IMG_Load_RW, 3.2.3 IMG_LoadTyped_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_Load_RW

3.2.2 IMG_Load_RW

SDL_Surface *IMG_Load_RW(SDL_RWops *src, int freesrc)

src
The source SDL_RWops as a pointer. The image is loaded from this.
freesrc
A non-zero value mean is will automatically close/free the src for you.

Load src for use as a surface. This can load all supported image formats, except TGA. Using SDL_RWops is not covered here, but they enable you to load from almost any source.
Note: If the image format loader requires initialization, it will attempt to do that the first time it is needed if you have not already called IMG_Init to load support for your image format.
Note: If the image format supports a transparent pixel, SDL_image will set the colorkey for the surface. You can enable RLE acceleration on the surface afterwards by calling:
SDL_SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors.

// load sample.png in to image
SDL_Surface *image;
image=IMG_Load_RW(SDL_RWFromFile("sample.png", "rb"), 1);
if(!image) {
    printf("IMG_Load_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.1 IMG_Load, 3.2.3 IMG_LoadTyped_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_LoadTyped_RW

3.2.3 IMG_LoadTyped_RW

SDL_Surface *IMG_LoadTyped_RW(SDL_RWops *src, int freesrc, char *type)

src
The source SDL_RWops as a pointer. The image is loaded from this.
freesrc
A non-zero value mean is will automatically close/free the src for you.
type
A string that indicates which format type to interpret the image as.
Here is a list of the currently recognized strings (case is not important):
"BMP"
"CUR"
"GIF"
"ICO"
"JPG"
"LBM"
"PCX"
"PNG"
"PNM"
"TGA"
"TIF"
"XCF"
"XPM"
"XV"

Load src for use as a surface. This can load all supported image formats. This method does not guarantee that the format specified by type is the format of the loaded image, except in the case when TGA format is specified (or any other non-magicable format in the future). Using SDL_RWops is not covered here, but they enable you to load from almost any source.
Note: If the image format loader requires initialization, it will attempt to do that the first time it is needed if you have not already called IMG_Init to load support for your image format.
Note: If the image format supports a transparent pixel, SDL_image will set the colorkey for the surface. You can enable RLE acceleration on the surface afterwards by calling:
SDL_SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors.

// load sample.tga into image
SDL_Surface *image;
image=IMG_LoadTyped_RW(SDL_RWFromFile("sample.tga", "rb"), 1, "TGA");
if(!image) {
    printf("IMG_LoadTyped_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.1 IMG_Load, 3.2.2 IMG_Load_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_LoadCUR_RW

3.2.4 IMG_LoadCUR_RW

SDL_Surface *IMG_LoadCUR_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The icon image is loaded from this.

Load src as a Windows Cursor image for use as a surface, if BMP support is compiled into the SDL_image library. The CUR's mask is put into to per pixel alpha in the surface. For files with multiple images, the first one found with the highest color count is chosen.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if BMP is not supported, or a read error.

// load sample.cur into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.cur", "rb");
image=IMG_LoadCUR_RW(rwop);
if(!image) {
    printf("IMG_LoadCUR_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.1 IMG_isCUR

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_LoadICO_RW

3.2.5 IMG_LoadICO_RW

SDL_Surface *IMG_LoadICO_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The icon image is loaded from this.

Load src as a Windows Icon image for use as a surface, if BMP support is compiled into the SDL_image library. The ICO's mask is put into to per pixel alpha in the surface. For files with multiple images, the first one found with the highest color count is chosen.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if BMP is not supported, or a read error.

// load sample.ico into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.ico", "rb");
image=IMG_LoadICO_RW(rwop);
if(!image) {
    printf("IMG_LoadICO_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.2 IMG_isICO

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_LoadBMP_RW

3.2.6 IMG_LoadBMP_RW

SDL_Surface *IMG_LoadBMP_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The BMP image is loaded from this.

Load src as a BMP image for use as a surface, if BMP support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if BMP is not supported, or a read error.

// load sample.bmp into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.bmp", "rb");
image=IMG_LoadBMP_RW(rwop);
if(!image) {
    printf("IMG_LoadBMP_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.3 IMG_isBMP

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_LoadPNM_RW

3.2.7 IMG_LoadPNM_RW

SDL_Surface *IMG_LoadPNM_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The PNM image is loaded from this.

Load src as a PNM image for use as a surface, if PNM support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if PNM is not supported, or a read error.

// load sample.pnm into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.pnm", "rb");
image=IMG_LoadPNM_RW(rwop);
if(!image) {
    printf("IMG_LoadPNM_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.4 IMG_isPNM

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_LoadXPM_RW

3.2.8 IMG_LoadXPM_RW

SDL_Surface *IMG_LoadXPM_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The XPM image is loaded from this.

Load src as a XPM image for use as a surface, if XPM support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if XPM is not supported, or a read error.

// load sample.xpm into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xpm", "rb");
image=IMG_LoadXPM_RW(rwop);
if(!image) {
    printf("IMG_LoadXPM_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.2.18 IMG_ReadXPMFromArray, 3.3.5 IMG_isXPM

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_LoadXCF_RW

3.2.9 IMG_LoadXCF_RW

SDL_Surface *IMG_LoadXCF_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The XCF image is loaded from this.

Load src as a XCF image for use as a surface, if XCF support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if XCF is not supported, or a read error.

// load sample.xcf into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xcf", "rb");
image=IMG_LoadXCF_RW(rwop);
if(!image) {
    printf("IMG_LoadXCF_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.6 IMG_isXCF

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_LoadPCX_RW

3.2.10 IMG_LoadPCX_RW

SDL_Surface *IMG_LoadPCX_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The PCX image is loaded from this.

Load src as a PCX image for use as a surface, if PCX support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if PCX is not supported, or a read error.

// load sample.pcx into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.pcx", "rb");
image=IMG_LoadPCX_RW(rwop);
if(!image) {
    printf("IMG_LoadPCX_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.7 IMG_isPCX

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_LoadGIF_RW

3.2.11 IMG_LoadGIF_RW

SDL_Surface *IMG_LoadGIF_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The GIF image is loaded from this.

Load src as a GIF image for use as a surface, if GIF support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if GIF is not supported, or a read error.

// load sample.gif into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.gif", "rb");
image=IMG_LoadGIF_RW(rwop);
if(!image) {
    printf("IMG_LoadGIF_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.8 IMG_isGIF

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_LoadJPG_RW

3.2.12 IMG_LoadJPG_RW

SDL_Surface *IMG_LoadJPG_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The JPG image is loaded from this.

Load src as a JPG image for use as a surface, if JPG support is compiled into the SDL_image library.
Note: If the image format loader requires initialization, it will attempt to do that the first time it is needed if you have not already called IMG_Init to load support for your image format.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if JPG is not supported, or a read error.

// load sample.jpg into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.jpg", "rb");
image=IMG_LoadJPG_RW(rwop);
if(!image) {
    printf("IMG_LoadJPG_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.3 IMG_LoadTyped_RW, 3.3.9 IMG_isJPG

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_LoadTIF_RW

3.2.13 IMG_LoadTIF_RW

SDL_Surface *IMG_LoadTIF_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The TIF image is loaded from this.

Load src as a TIF image for use as a surface, if TIF support is compiled into the SDL_image library.
Note: If the image format loader requires initialization, it will attempt to do that the first time it is needed if you have not already called IMG_Init to load support for your image format.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if TIF is not supported, or a read error.

// load sample.tif into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.tif", "rb");
image=IMG_LoadTIF_RW(rwop);
if(!image) {
    printf("IMG_LoadTIF_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.3 IMG_LoadTyped_RW, 3.3.10 IMG_isTIF

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_LoadPNG_RW

3.2.14 IMG_LoadPNG_RW

SDL_Surface *IMG_LoadPNG_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The PNG image is loaded from this.

Load src as a PNG image for use as a surface, if PNG support is compiled into the SDL_image library.
Note: If the image format loader requires initialization, it will attempt to do that the first time it is needed if you have not already called IMG_Init to load support for your image format.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if PNG is not supported, or a read error.

// load sample.png into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.png", "rb");
image=IMG_LoadPNG_RW(rwop);
if(!image) {
    printf("IMG_LoadPNG_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.1.2 IMG_Init, 3.2.3 IMG_LoadTyped_RW, 3.3.11 IMG_isPNG

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_LoadTGA_RW

3.2.15 IMG_LoadTGA_RW

SDL_Surface *IMG_LoadTGA_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The TGA image is loaded from this.

Load src as a TGA image for use as a surface, if TGA support is compiled into the SDL_image library. If you try to load a non TGA image, you might succeed even when it's not TGA image formatted data, this is because the TGA has no magic, which is a way of identifying a filetype from a signature in it's contents. So be careful with this.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if TGA is not supported, or a read error.

// load sample.tga into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.tga", "rb");
image=IMG_LoadTGA_RW(rwop);
if(!image) {
    printf("IMG_LoadTGA_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_LoadLBM_RW

3.2.16 IMG_LoadLBM_RW

SDL_Surface *IMG_LoadLBM_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The LBM image is loaded from this.

Load src as a LBM image for use as a surface, if LBM support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if LBM is not supported, or a read error.

// load sample.lbm into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.lbm", "rb");
image=IMG_LoadLBM_RW(rwop);
if(!image) {
    printf("IMG_LoadLBM_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.12 IMG_isLBM

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_LoadXV_RW

3.2.17 IMG_LoadXV_RW

SDL_Surface *IMG_LoadXV_RW(SDL_RWops *src)

src
The source SDL_RWops as a pointer. The XV image is loaded from this.

Load src as a XV thumbnail image for use as a surface, if XV support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if XV is not supported, or a read error.

// load sample.xv into image
SDL_Surface *image;
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xv", "rb");
image=IMG_LoadXV_RW(rwop);
if(!image) {
    printf("IMG_LoadXV_RW: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.3 IMG_LoadTyped_RW, 3.3.13 IMG_isXV

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_ReadXPMFromArray

3.2.18 IMG_ReadXPMFromArray

SDL_Surface *IMG_ReadXPMFromArray(char **xpm)

xpm
The source xpm data. The XPM image is loaded from this. XPM files are C header files that define a char **variable, that variable name is what you use here.

Load xpm as a XPM image for use as a surface, if XPM support is compiled into the SDL_image library.

Returns: a pointer to the image as a new SDL_Surface. NULL is returned on errors, like if XPM is not supported, or a read error.

// load sample.xpm into image
#include "sample.xpm"
SDL_Surface *image;
image=IMG_ReadXPMFromArray(sample_xpm);
if(!image) {
    printf("IMG_ReadXPMFromArray: %s\n", IMG_GetError());
    // handle error
}

See Also:
3.2.8 IMG_LoadXPM_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: Info

3.3 Info

These functions are tests for specific file formats. They also show if the format is supported in the linked SDL_image library, assuming you have a valid image of that type.

3.3.3 IMG_isBMP | Test for valid, supportted BMP file
3.3.1 IMG_isCUR | Test for valid, supportted CUR file
3.3.8 IMG_isGIF | Test for valid, supportted GIF file
3.3.2 IMG_isICO | Test for valid, supportted ICO file
3.3.9 IMG_isJPG | Test for valid, supportted JPG file
3.3.12 IMG_isLBM | Test for valid, supportted LBM file
3.3.7 IMG_isPCX | Test for valid, supportted PCX file
3.3.11 IMG_isPNG | Test for valid, supportted PNG file
3.3.4 IMG_isPNM | Test for valid, supportted PNM file
3.3.10 IMG_isTIF | Test for valid, supportted TIF file
3.3.6 IMG_isXCF | Test for valid, supportted XCF file
3.3.5 IMG_isXPM | Test for valid, supportted XPM file
3.3.13 IMG_isXV | Test for valid, supportted XV file

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_isCUR

3.3.1 IMG_isCUR

int IMG_isCUR(SDL_RWops *src)

src

If the BMP format is supported, then the image data is tested to see if it is readable as a CUR, otherwise it returns false (Zero).

Returns: 1 if the image is a CUR and the BMP format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.cur to see if it is a CUR
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.cur", "rb");
if(IMG_isCUR(rwop))
    printf("sample.cur is a CUR file.\n");
else
    printf("sample.cur is not a CUR file, or BMP support is not available.\n");

See Also:
3.2.4 IMG_LoadCUR_RW, 3.2.3 IMG_LoadTyped_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_isICO

3.3.2 IMG_isICO

int IMG_isICO(SDL_RWops *src)

src

If the BMP format is supported, then the image data is tested to see if it is readable as an ICO, otherwise it returns false (Zero).

Returns: 1 if the image is an ICO and the BMP format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.ico to see if it is an ICO
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.ico", "rb");
if(IMG_isICO(rwop))
    printf("sample.ico is an ICO file.\n");
else
    printf("sample.ico is not an ICO file, or BMP support is not available.\n");

See Also:
3.2.5 IMG_LoadICO_RW, 3.2.3 IMG_LoadTyped_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_isBMP

3.3.3 IMG_isBMP

int IMG_isBMP(SDL_RWops *src)

src

If the BMP format is supported, then the image data is tested to see if it is readable as a BMP, otherwise it returns false (Zero).

Returns: 1 if the image is a BMP and the BMP format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.bmp to see if it is a BMP
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.bmp", "rb");
if(IMG_isBMP(rwop))
    printf("sample.bmp is a BMP file.\n");
else
    printf("sample.bmp is not a BMP file, or BMP support is not available.\n");

See Also:
3.2.6 IMG_LoadBMP_RW, 3.2.3 IMG_LoadTyped_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_isPNM

3.3.4 IMG_isPNM

int IMG_isPNM(SDL_RWops *src)

src

If the PNM format is supported, then the image data is tested to see if it is readable as a PNM, otherwise it returns false (Zero).

Returns: 1 if the image is a PNM and the PNM format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.pnm to see if it is a PNM
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.pnm", "rb");
if(IMG_isPNM(rwop))
    printf("sample.pnm is a PNM file.\n");
else
    printf("sample.pnm is not a PNM file, or PNM support is not available.\n");

See Also:
3.2.7 IMG_LoadPNM_RW, 3.2.3 IMG_LoadTyped_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_isXPM

3.3.5 IMG_isXPM

int IMG_isXPM(SDL_RWops *src)

src

If the XPM format is supported, then the image data is tested to see if it is readable as a XPM, otherwise it returns false (Zero).

Returns: 1 if the image is a XPM and the XPM format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.xpm to see if it is a XPM
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xpm", "rb");
if(IMG_isXPM(rwop))
    printf("sample.xpm is a XPM file.\n");
else
    printf("sample.xpm is not a XPM file, or XPM support is not available.\n");

See Also:
3.2.8 IMG_LoadXPM_RW, 3.2.3 IMG_LoadTyped_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_isXCF

3.3.6 IMG_isXCF

int IMG_isXCF(SDL_RWops *src)

src

If the XCF format is supported, then the image data is tested to see if it is readable as a XCF, otherwise it returns false (Zero).

Returns: 1 if the image is a XCF and the XCF format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.xcf to see if it is a XCF
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xcf", "rb");
if(IMG_isXCF(rwop))
    printf("sample.xcf is a XCF file.\n");
else
    printf("sample.xcf is not a XCF file, or XCF support is not available.\n");

See Also:
3.2.9 IMG_LoadXCF_RW, 3.2.3 IMG_LoadTyped_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_isPCX

3.3.7 IMG_isPCX

int IMG_isPCX(SDL_RWops *src)

src

If the PCX format is supported, then the image data is tested to see if it is readable as a PCX, otherwise it returns false (Zero).

Returns: 1 if the image is a PCX and the PCX format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.pcx to see if it is a PCX
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.pcx", "rb");
if(IMG_isPCX(rwop))
    printf("sample.pcx is a PCX file.\n");
else
    printf("sample.pcx is not a PCX file, or PCX support is not available.\n");

See Also:
3.2.10 IMG_LoadPCX_RW, 3.2.3 IMG_LoadTyped_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_isGIF

3.3.8 IMG_isGIF

int IMG_isGIF(SDL_RWops *src)

src

If the GIF format is supported, then the image data is tested to see if it is readable as a GIF, otherwise it returns false (Zero).

Returns: 1 if the image is a GIF and the GIF format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.gif to see if it is a GIF
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.gif", "rb");
if(IMG_isGIF(rwop))
    printf("sample.gif is a GIF file.\n");
else
    printf("sample.gif is not a GIF file, or GIF support is not available.\n");

See Also:
3.2.11 IMG_LoadGIF_RW, 3.2.3 IMG_LoadTyped_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_isJPG

3.3.9 IMG_isJPG

int IMG_isJPG(SDL_RWops *src)

src

If the JPG format is supported, then the image data is tested to see if it is readable as a JPG, otherwise it returns false (Zero).

Returns: 1 if the image is a JPG and the JPG format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.jpg to see if it is a JPG
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.jpg", "rb");
if(IMG_isJPG(rwop))
    printf("sample.jpg is a JPG file.\n");
else
    printf("sample.jpg is not a JPG file, or JPG support is not available.\n");

See Also:
3.2.12 IMG_LoadJPG_RW, 3.2.3 IMG_LoadTyped_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_isTIF

3.3.10 IMG_isTIF

int IMG_isTIF(SDL_RWops *src)

src

If the TIF format is supported, then the image data is tested to see if it is readable as a TIF, otherwise it returns false (Zero).

Returns: 1 if the image is a TIF and the TIF format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.tif to see if it is a TIF
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.tif", "rb");
if(IMG_isTIF(rwop))
    printf("sample.tif is a TIF file.\n");
else
    printf("sample.tif is not a TIF file, or TIF support is not available.\n");

See Also:
3.2.13 IMG_LoadTIF_RW, 3.2.3 IMG_LoadTyped_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_isPNG

3.3.11 IMG_isPNG

int IMG_isPNG(SDL_RWops *src)

src

If the PNG format is supported, then the image data is tested to see if it is readable as a PNG, otherwise it returns false (Zero).

Returns: 1 if the image is a PNG and the PNG format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.png to see if it is a PNG
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.png", "rb");
if(IMG_isPNG(rwop))
    printf("sample.png is a PNG file.\n");
else
    printf("sample.png is not a PNG file, or PNG support is not available.\n");

See Also:
3.2.14 IMG_LoadPNG_RW, 3.2.3 IMG_LoadTyped_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_isLBM

3.3.12 IMG_isLBM

int IMG_isLBM(SDL_RWops *src)

src

If the LBM format is supported, then the image data is tested to see if it is readable as a LBM, otherwise it returns false (Zero).

Returns: 1 if the image is a LBM and the LBM format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.lbm to see if it is a LBM
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.lbm", "rb");
if(IMG_isLBM(rwop))
    printf("sample.lbm is a LBM file.\n");
else
    printf("sample.lbm is not a LBM file, or LBM support is not available.\n");

See Also:
3.2.16 IMG_LoadLBM_RW, 3.2.3 IMG_LoadTyped_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_isXV

3.3.13 IMG_isXV

int IMG_isXV(SDL_RWops *src)

src

If the XV format is supported, then the image data is tested to see if it is readable as an XV thumbnail, otherwise it returns false (Zero).

Returns: 1 if the image is an XV thumbnail and the XV format support is compiled into SDL_image. 0 is returned otherwise.

// Test sample.xv to see if it is an XV thumbnail
SDL_RWops *rwop;
rwop=SDL_RWFromFile("sample.xv", "rb");
if(IMG_isXV(rwop))
    printf("sample.xv is an XV file.\n");
else
    printf("sample.xv is not an XV file, or XV support is not available.\n");

See Also:
3.2.17 IMG_LoadXV_RW, 3.2.3 IMG_LoadTyped_RW

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: Errors

3.4 Errors

These functions are used for error status strings that should help the user and developer understand why a function failed.

3.4.1 IMG_SetError | Set the current error string
3.4.2 IMG_GetError | Get the current error string

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_SetError

3.4.1 IMG_SetError

void IMG_SetError(const char *fmt, ...)

This is the same as SDL_SetError, which sets the error string which may be fetched with IMG_GetError (or SDL_GetError). This functions acts like printf, except that it is limited to SDL_ERRBUFIZE(1024) chars in length. It only accepts the following format types: %s, %d, %f, %p. No variations are supported, like %.2f would not work. For any more specifics read the SDL docs.

int myimagefunc(int i) {
    IMG_SetError("myimagefunc is not implemented! %d was passed in.",i);
    return(-1);
}

See Also:
3.4.2 IMG_GetError

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: IMG_GetError

3.4.2 IMG_GetError

char *IMG_GetError()

This is the same as SDL_GetError, which returns the last error set as a string which you may use to tell the user what happened when an error status has been returned from an SDL_image function call.

Returns: a char pointer (string) containing a humam readble version or the reason for the last error that occured.

printf("Oh My Goodness, an error : %s", IMG_GetError());

See Also:
3.4.1 IMG_SetError

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: Defines

4. Defines

IMG_MAJOR_VERSION
1
SDL_image library major number at compilation time
IMG_MINOR_VERSION
2
SDL_image library minor number at compilation time
IMG_PATCHLEVEL
8
SDL_image library patch level at compilation time
IMG_INIT_JPG
1
IMG_Init JPG image format support flag
IMG_INIT_PNG
2
IMG_Init PNG image format support flag
IMG_INIT_TIF
4
IMG_Init TIF image format support flag

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: Index

Index

Jump to: I R S

 | Index Entry | Section
I |  |
 | IMG_GetError | 3.4.2 IMG_GetError
 | IMG_Init | 3.1.2 IMG_Init
 | IMG_INIT_JPG | 4. Defines
 | IMG_INIT_PNG | 4. Defines
 | IMG_INIT_TIF | 4. Defines
 | IMG_isBMP | 3.3.3 IMG_isBMP
 | IMG_isCUR | 3.3.1 IMG_isCUR
 | IMG_isGIF | 3.3.8 IMG_isGIF
 | IMG_isICO | 3.3.2 IMG_isICO
 | IMG_isJPG | 3.3.9 IMG_isJPG
 | IMG_isLBM | 3.3.12 IMG_isLBM
 | IMG_isPCX | 3.3.7 IMG_isPCX
 | IMG_isPNG | 3.3.11 IMG_isPNG
 | IMG_isPNM | 3.3.4 IMG_isPNM
 | IMG_isTIF | 3.3.10 IMG_isTIF
 | IMG_isXCF | 3.3.6 IMG_isXCF
 | IMG_isXPM | 3.3.5 IMG_isXPM
 | IMG_isXV | 3.3.13 IMG_isXV
 | IMG_Linked_Version | 3.1.1 IMG_Linked_Version
 | IMG_Load | 3.2.1 IMG_Load
 | IMG_Load_RW | 3.2.2 IMG_Load_RW
 | IMG_LoadBMP_RW | 3.2.6 IMG_LoadBMP_RW
 | IMG_LoadCUR_RW | 3.2.4 IMG_LoadCUR_RW
 | IMG_LoadGIF_RW | 3.2.11 IMG_LoadGIF_RW
 | IMG_LoadICO_RW | 3.2.5 IMG_LoadICO_RW
 | IMG_LoadJPG_RW | 3.2.12 IMG_LoadJPG_RW
 | IMG_LoadLBM_RW | 3.2.16 IMG_LoadLBM_RW
 | IMG_LoadPCX_RW | 3.2.10 IMG_LoadPCX_RW
 | IMG_LoadPNG_RW | 3.2.14 IMG_LoadPNG_RW
 | IMG_LoadPNM_RW | 3.2.7 IMG_LoadPNM_RW
 | IMG_LoadTGA_RW | 3.2.15 IMG_LoadTGA_RW
 | IMG_LoadTIF_RW | 3.2.13 IMG_LoadTIF_RW
 | IMG_LoadTyped_RW | 3.2.3 IMG_LoadTyped_RW
 | IMG_LoadXCF_RW | 3.2.9 IMG_LoadXCF_RW
 | IMG_LoadXPM_RW | 3.2.8 IMG_LoadXPM_RW
 | IMG_LoadXV_RW | 3.2.17 IMG_LoadXV_RW
 | IMG_MAJOR_VERSION | 4. Defines
 | IMG_MINOR_VERSION | 4. Defines
 | IMG_PATCHLEVEL | 4. Defines
 | IMG_Quit | 3.1.3 IMG_Quit
 | IMG_ReadXPMFromArray | 3.2.18 IMG_ReadXPMFromArray
 | IMG_SetError | 3.4.1 IMG_SetError
R |  |
 | README | 1. Overview
S |  |
 | sdl-config | 2.2 Compiling
 | SDL_IMAGE_VERSION | 3.1.1 IMG_Linked_Version
 | SDL_Surface | 3.2 Loading

Jump to: I R S

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.4: Music

4.5 Music

These functions work with music. Music is not played on a normal mixer channel. Music is therefore manipulated separately, except in post-processing hooks.

Load
4.5.1 Mix_LoadMUS Load a music file into a Mix_Music
Free
4.5.2 Mix_FreeMusic Free a Mix_Music
Playing
4.5.3 Mix_PlayMusic | Play music, with looping
4.5.4 Mix_FadeInMusic | Play music, with looping, and fade in
4.5.5 Mix_FadeInMusicPos | Play music from a start point, with looping, and fade in
4.5.6 Mix_HookMusic | Hook for a custom music player
Settings
4.5.7 Mix_VolumeMusic | Set music volume
4.5.8 Mix_PauseMusic | Pause music
4.5.9 Mix_ResumeMusic | Resume paused music
4.5.10 Mix_RewindMusic | Rewind music to beginning
4.5.11 Mix_SetMusicPosition | Set position of playback in stream
4.5.12 Mix_SetMusicCMD | Use external program for music playback
Stopping
4.5.13 Mix_HaltMusic | Stop music playback
4.5.14 Mix_FadeOutMusic | Stop music, with fade out
4.5.15 Mix_HookMusicFinished | Set a callback for when music stops
Info
4.5.16 Mix_GetMusicType | Get the music encoding type
4.5.17 Mix_PlayingMusic | Test whether music is playing
4.5.18 Mix_PausedMusic | Test whether music is paused
4.5.19 Mix_FadingMusic | Get status of current music fade activity
4.5.20 Mix_GetMusicHookData | Retrieve the Mix_HookMusic arg

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_LoadMUS

4.5.1 Mix_LoadMUS

Mix_Music *Mix_LoadMUS(const char *file)

file
Name of music file to use.

Load music file to use. This can load WAVE, MOD, MIDI, OGG, MP3, and any file that you use a command to play with.
If you are using an external command to play the music, you must call Mix_SetMusicCMD before this, otherwise the internal players will be used. Alternatively, if you have set an external command up and don't want to use it, you must call Mix_SetMusicCMD(NULL) to use the built-in players again.

Returns: A pointer to a Mix_Music. NULL is returned on errors.

// load the MP3 file "music.mp3" to play as music
Mix_Music *music;
music=Mix_LoadMUS("music.mp3");
if(!music) {
    printf("Mix_LoadMUS(\"music.mp3\"): %s\n", Mix_GetError());
    // this might be a critical error...
}

See Also:
5.2 Mix_Music, 4.5.12 Mix_SetMusicCMD, 4.5.3 Mix_PlayMusic, 4.5.4 Mix_FadeInMusic, 4.5.5 Mix_FadeInMusicPos

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_FreeMusic

4.5.2 Mix_FreeMusic

void Mix_FreeMusic(Mix_Music *music)

music
Pointer to Mix_Music to free.

Free the loaded music. If music is playing it will be halted. If music is fading out, then this function will wait (blocking) until the fade out is complete.

// free music
Mix_Music *music;
Mix_FreeMusic(music);
music=NULL; // so we know we freed it...

See Also:
4.5.1 Mix_LoadMUS

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_PlayMusic

4.5.3 Mix_PlayMusic

int Mix_PlayMusic(Mix_Music *music, int loops)

music
Pointer to Mix_Music to play.
loops
number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)

Play the loaded music loop times through from start to finish. The previous music will be halted, or if fading out it waits (blocking) for that to finish.

Returns: 0 on success, or -1 on errors.

// play music forever
// Mix_Music *music; // I assume this has been loaded already
if(Mix_PlayMusic(music, -1)==-1) {
    printf("Mix_PlayMusic: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
4.5.4 Mix_FadeInMusic

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_FadeInMusic

4.5.4 Mix_FadeInMusic

int Mix_FadeInMusic(Mix_Music *music, int loops, int ms)

music
Pointer to Mix_Music to play.
loops
number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)
ms
Milliseconds for the fade-in effect to complete.

Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish.
The fade in effect only applies to the first loop.
Any previous music will be halted, or if it is fading out it will wait (blocking) for the fade to complete.
This function is the same as Mix_FadeInMusicPos(music, loops, ms, 0).

Returns: 0 on success, or -1 on errors.

// play music forever, fading in over 2 seconds
// Mix_Music *music; // I assume this has been loaded already
if(Mix_FadeInMusic(music, -1, 2000)==-1) {
    printf("Mix_FadeInMusic: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
4.5.3 Mix_PlayMusic, 4.5.5 Mix_FadeInMusicPos

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_FadeInMusicPos

4.5.5 Mix_FadeInMusicPos

int Mix_FadeInMusicPos(Mix_Music *music, int loops, int ms, double position)

music
Pointer to Mix_Music to play.
loops
number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)
ms
Milliseconds for the fade-in effect to complete.
position
Posistion to play from, see Mix_SetMusicPosition for meaning.

Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish.
The fade in effect only applies to the first loop.
The first time the music is played, it posistion will be set to posistion, which means different things for different types of music files, see Mix_SetMusicPosition for more info on that.
Any previous music will be halted, or if it is fading out it will wait (blocking) for the fade to complete.

Returns: 0 on success, or -1 on errors.

// play music forever, fading in over 2 seconds
// Mix_Music *music; // I assume this has been loaded already
if(Mix_FadeInMusicPos(music, -1, 2000)==-1) {
    printf("Mix_FadeInMusic: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
4.5.3 Mix_PlayMusic, 4.5.4 Mix_FadeInMusic, 4.5.11 Mix_SetMusicPosition

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_HookMusic

4.5.6 Mix_HookMusic

void Mix_HookMusic(void (*mix_func)(void *udata, Uint8 *stream, int len),
                   void *arg)

mix_func
Function pointer to a music player mixer function.
NULL will stop the use of the music player, returning the mixer to using the internal music players like usual.
arg
This is passed to the mix_func's udata parameter when it is called.

This sets up a custom music player function. The function will be called with arg passed into the udata parameter when the mix_func is called. The stream parameter passes in the audio stream buffer to be filled with len bytes of music. The music player will then be called automatically when the mixer needs it. Music playing will start as soon as this is called. All the music playing and stopping functions have no effect on music after this. Pause and resume will work. Using a custom music player and the internal music player is not possible, the custom music player takes priority. To stop the custom music player call Mix_HookMusic(NULL, NULL).
NOTE: NEVER call SDL_Mixer functions, nor SDL_LockAudio, from a callback function.

// make a music play function
// it expects udata to be a pointer to an int
void myMusicPlayer(void *udata, Uint8 *stream, int len)
{
    int i, pos=*(int*)udata;

    // fill buffer with...uh...music...
    for(i=0; i<len; i++)
        stream[i]=(i+pos)&ff;

    // set udata for next time
    pos+=len;
    *(int*)udata=pos;
}
...
// use myMusicPlayer for playing...uh...music
int music_pos=0;
Mix_HookMusic(myMusicPlayer, &music_pos);

See Also:
4.5.12 Mix_SetMusicCMD, 4.5.20 Mix_GetMusicHookData

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_VolumeMusic

4.5.7 Mix_VolumeMusic

int Mix_VolumeMusic(int volume)

volume
Music volume, from 0 to MIX_MAX_VOLUME(128).
Values greater than MIX_MAX_VOLUME will use MIX_MAX_VOLUME.
-1 does not set the volume, but does return the current volume setting.

Set the volume to volume, if it is 0 or greater, and return the previous volume setting. Setting the volume during a fade will not work, the faders use this function to perform their effect! Setting volume while using an external music player set by Mix_SetMusicCMD will have no effect, and Mix_GetError will show the reason why not.

Returns: The previous volume setting.

// set the music volume to 1/2 maximum, and then check it
printf("volume was    : %d\n", Mix_VolumeMusic(MIX_MAX_VOLUME/2));
printf("volume is now : %d\n", Mix_VolumeMusic(-1));

See Also:
4.5.4 Mix_FadeInMusic, 4.5.14 Mix_FadeOutMusic, 4.5.12 Mix_SetMusicCMD

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_PauseMusic

4.5.8 Mix_PauseMusic

void Mix_PauseMusic()

Pause the music playback. You may halt paused music.
Note: Music can only be paused if it is actively playing.

// pause music playback
Mix_PauseMusic();

See Also:
4.5.9 Mix_ResumeMusic, 4.5.18 Mix_PausedMusic, 4.5.13 Mix_HaltMusic

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_ResumeMusic

4.5.9 Mix_ResumeMusic

void Mix_ResumeMusic()

Unpause the music. This is safe to use on halted, paused, and already playing music.

// resume music playback
Mix_ResumeMusic();

See Also:
4.5.8 Mix_PauseMusic, 4.5.18 Mix_PausedMusic

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_RewindMusic

4.5.10 Mix_RewindMusic

void Mix_RewindMusic()

Rewind the music to the start. This is safe to use on halted, paused, and already playing music. It is not useful to rewind the music immediately after starting playback, because it starts at the beginning by default.

This function only works for these streams: MOD, OGG, MP3, Native MIDI.

// rewind music playback to the start
Mix_RewindMusic();

See Also:
4.5.3 Mix_PlayMusic

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_SetMusicPosition

4.5.11 Mix_SetMusicPosition

int Mix_SetMusicPosition(double position)

position
Posistion to play from.

Set the position of the currently playing music. The position takes different meanings for different music sources. It only works on the music sources listed below.

MOD
The double is cast to Uint16 and used for a pattern number in the module.
Passing zero is similar to rewinding the song.
OGG
Jumps to position seconds from the beginning of the song.
MP3
Jumps to position seconds from the current position in the stream.
So you may want to call Mix_RewindMusic before this.
Does not go in reverse...negative values do nothing.

Returns: 0 on success, or -1 if the codec doesn't support this function.

// skip one minute into the song, from the start
// this assumes you are playing an MP3
Mix_RewindMusic();
if(Mix_SetMusicPosition(60.0)==-1) {
    printf("Mix_SetMusicPosition: %s\n", Mix_GetError());
}

See Also:
4.5.5 Mix_FadeInMusicPos

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_SetMusicCMD

4.5.12 Mix_SetMusicCMD

int Mix_SetMusicCMD(const char *command)

command
System command to play the music. Should be a complete command, as if typed in to the command line, but it should expect the filename to be added as the last argument.
NULL will turn off using an external command for music, returning to the internal music playing functionality.

Setup a command line music player to use to play music. Any music playing will be halted. The music file to play is set by calling Mix_LoadMUS(filename), and the filename is appended as the last argument on the commandline. This allows you to reuse the music command to play multiple files. The command will be sent signals SIGTERM to halt, SIGSTOP to pause, and SIGCONT to resume. The command program should react correctly to those signals for it to function properly with SDL_Mixer. Mix_VolumeMusic has no effect when using an external music player, and Mix_GetError will have an error code set. You should set the music volume in the music player's command if the music player supports that. Looping music works, by calling the command again when the previous music player process has ended. Playing music through a command uses a forked process to execute the music command.
To use the internal music players set the command to NULL.
NOTE: External music is not mixed by SDL_mixer, so no post-processing hooks will be for music.
NOTE: Playing music through an external command may not work if the sound driver does not support multiple openings of the audio device, since SDL_Mixer already has the audio device open for playing samples through channels.
NOTE: Commands are not totally portable, so be careful.

Returns: 0 on success, or -1 on any errors, such as running out of memory.

// use mpg123 to play music
Mix_Music *music=NULL;
if(Mix_SetMusicCMD("mpg123 -q")==-1) {
    perror("Mix_SetMusicCMD");
} else {
    // play some mp3 file
    music=Mix_LoadMUS("music.mp3");
    if(music) {
        Mix_PlayMusic(music,1);
    }
}

See Also:
4.5.3 Mix_PlayMusic, 4.5.7 Mix_VolumeMusic

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_HaltMusic

4.5.13 Mix_HaltMusic

int Mix_HaltMusic()

Halt playback of music. This interrupts music fader effects. Any callback set by Mix_HookMusicFinished will be called when the music stops.

Returns: always returns zero. (even more silly than Mix_HaltGroup)

// halt music playback
Mix_HaltMusic();

See Also:
4.5.14 Mix_FadeOutMusic, 4.5.15 Mix_HookMusicFinished

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_FadeOutMusic

4.5.14 Mix_FadeOutMusic

int Mix_FadeOutMusic(int ms)

ms
Milliseconds of time that the fade-out effect should take to go to silence, starting now.

Gradually fade out the music over ms milliseconds starting from now. The music will be halted after the fade out is completed. Only when music is playing and not fading already are set to fade out, including paused channels. Any callback set by Mix_HookMusicFinished will be called when the music finishes fading out.

Returns: 1 on success, 0 on failure.

// fade out music to finish 3 seconds from now
while(!Mix_FadeOutMusic(3000) && Mix_PlayingMusic()) {
    // wait for any fades to complete
    SDL_Delay(100);
}

See Also:
4.5.13 Mix_HaltMusic, 4.5.19 Mix_FadingMusic, 4.5.17 Mix_PlayingMusic, 4.5.15 Mix_HookMusicFinished

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_HookMusicFinished

4.5.15 Mix_HookMusicFinished

void Mix_HookMusicFinished(void (*music_finished)())

music_finished
Function pointer to a void function().
NULL will remove the hook.

This sets up a function to be called when music playback is halted. Any time music stops, the music_finished function will be called. Call with NULL to remove the callback.
NOTE: NEVER call SDL_Mixer functions, nor SDL_LockAudio, from a callback function.

// make a music finished function
void musicFinished()
{
    printf("Music stopped.\n");
}
...
// use musicFinished for when music stops
Mix_HookMusicFinished(musicFinished);

See Also:
4.5.13 Mix_HaltMusic, 4.5.14 Mix_FadeOutMusic

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_GetMusicType

4.5.16 Mix_GetMusicType

Mix_MusicType Mix_GetMusicType(const Mix_Music *music)

music
The music to get the type of.
NULL will get the currently playing music type.

Tells you the file format encoding of the music. This may be handy when used with Mix_SetMusicPosition, and other music functions that vary based on the type of music being played. If you want to know the type of music currently being played, pass in NULL to music.

Returns: The type of music or if music is NULL then the currently playing music type, otherwise MUS_NONE if no music is playing.

// print the type of music currently playing
switch(Mix_GetMusicType(NULL))
{
    case MUS_NONE:
    MUS_CMD:
        printf("Command based music is playing.\n");
        break;
    MUS_WAV:
        printf("WAVE/RIFF music is playing.\n");
        break;
    MUS_MOD:
        printf("MOD music is playing.\n");
        break;
    MUS_MID:
        printf("MIDI music is playing.\n");
        break;
    MUS_OGG:
        printf("OGG music is playing.\n");
        break;
    MUS_MP3:
        printf("MP3 music is playing.\n");
        break;
    default:
        printf("Unknown music is playing.\n");
        break;
}

See Also:
5.3 Mix_MusicType, 4.6.7 Mix_SetPosition

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_PlayingMusic

4.5.17 Mix_PlayingMusic

int Mix_PlayingMusic()

Tells you if music is actively playing, or not.
Note: Does not check if the channel has been paused.

Returns: Zero if the music is not playing, or 1 if it is playing.

// check if music is playing
printf("music is%s playing.\n", Mix_PlayingMusic()?"":" not");

See Also:
4.5.18 Mix_PausedMusic, 4.5.19 Mix_FadingMusic, 4.5.3 Mix_PlayMusic

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_PausedMusic

4.5.18 Mix_PausedMusic

int Mix_PausedMusic()

Tells you if music is paused, or not.
Note: Does not check if the music was been halted after it was paused, which may seem a little weird.

Returns: Zero if music is not paused. 1 if it is paused.

// check the music pause status
printf("music is%s paused\n", Mix_PausedMusic()?"":" not");

See Also:
4.5.17 Mix_PlayingMusic, 4.5.8 Mix_PauseMusic, 4.5.9 Mix_ResumeMusic

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_FadingMusic

4.5.19 Mix_FadingMusic

Mix_Fading Mix_FadingMusic()

Tells you if music is fading in, out, or not at all. Does not tell you if the channel is playing anything, or paused, so you'd need to test that separately.

Returns: the fading status. Never returns an error.

// check the music fade status
switch(Mix_FadingMusic()) {
    case MIX_NO_FADING:
        printf("Not fading music.\n");
        break;
    case MIX_FADING_OUT:
        printf("Fading out music.\n");
        break;
    case MIX_FADING_IN:
        printf("Fading in music.\n");
        break;
}

See Also:
5.4 Mix_Fading, 4.5.18 Mix_PausedMusic, 4.5.17 Mix_PlayingMusic, 4.5.5 Mix_FadeInMusicPos, 4.5.14 Mix_FadeOutMusic

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_GetMusicHookData

4.5.20 Mix_GetMusicHookData

void *Mix_GetMusicHookData()

Get the arg passed into Mix_HookMusic.

Returns: the arg pointer.

// retrieve the music hook data pointer
void *data;
data=Mix_GetMusicHookData();

See Also:
4.5.6 Mix_HookMusic

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Effects

4.6 Effects

These functions are for special effects processing. Not all effects are all that special. All effects are post processing routines that are either built-in to SDL_mixer or created by you. Effects can be applied to individual channels, or to the final mixed stream which contains all the channels including music.

Registration
4.6.1 Mix_RegisterEffect | Hook a processor to a channel
4.6.2 Mix_UnregisterEffect | Unhook a processor from a channel
4.6.3 Mix_UnregisterAllEffects | Unhook all processors from a channel
4.6.4 Mix_SetPostMix | Hook in a postmix processor
Built-in Processors
4.6.5 Mix_SetPanning | Stereo panning
4.6.6 Mix_SetDistance | Distance attenuation (volume)
4.6.7 Mix_SetPosition | Panning(angular) and distance
4.6.8 Mix_SetReverseStereo | Swap stereo left and right

The built-in processors: Mix_SetPanning, Mix_SetPosition, Mix_SetDistance, and
Mix_SetReverseStereo, all look for an environment variable, MIX_EFFECTSMAXSPEED to be defined. If the environment variable is defined these processors may use more memory or reduce the quality of the effects, all for better speed.

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_RegisterEffect

4.6.1 Mix_RegisterEffect

int Mix_RegisterEffect(int chan, Mix_EffectFunc_t f, Mix_EffectDone_t d,
                       void *arg)

chan
channel number to register f and d on.
Use MIX_CHANNEL_POST to process the postmix stream.
f
The function pointer for the effects processor.
d
The function pointer for any cleanup routine to be called when the channel is done playing a sample.
This may be NULL for any processors that don't need to clean up any memory or other dynamic data.
arg
A pointer to data to pass into the f's and d's udata parameter. It is a good place to keep the state data for the processor, especially if the processor is made to handle multiple channels at the same time.
This may be NULL, depending on the processor.

Hook a processor function f into a channel for post processing effects. You may just be reading the data and displaying it, or you may be altering the stream to add an echo. Most processors also have state data that they allocate as they are in use, this would be stored in the arg pointer data space. When a processor is finished being used, any function passed into d will be called, which is when your processor should clean up the data in the arg data space.
The effects are put into a linked list, and always appended to the end, meaning they always work on previously registered effects output. Effects may be added multiple times in a row. Effects are cumulative this way.

Returns: Zero on errors, such as a nonexisting channel.

// make a passthru processor function that does nothing...
void noEffect(int chan, void *stream, int len, void *udata)
{
    // you could work with stream here...
}
...
// register noEffect as a postmix processor
if(!Mix_RegisterEffect(MIX_CHANNEL_POST, noEffect, NULL, NULL)) {
    printf("Mix_RegisterEffect: %s\n", Mix_GetError());
}

See Also:
4.6.2 Mix_UnregisterEffect, 4.6.3 Mix_UnregisterAllEffects

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_UnregisterEffect

4.6.2 Mix_UnregisterEffect

int Mix_UnregisterEffect(int channel, Mix_EffectFunc_t f)

channel
Channel number to remove f from as a post processor.
Use MIX_CHANNEL_POST for the postmix stream.
f
The function to remove from channel.

Remove the oldest (first found) registered effect function f from the effect list for channel. This only removes the first found occurance of that function, so it may need to be called multiple times if you added the same function multiple times, just stop removing when Mix_UnregisterEffect returns an error, to remove all occurances of f from a channel.
If the channel is active the registered effect will have its Mix_EffectDone_t function called, if it was specified in Mix_RegisterEffect.

Returns: Zero on errors, such as invalid channel, or effect function not registered on channel.

// unregister the noEffect from the postmix effects
// this removes all occurances of noEffect registered to the postmix
while(Mix_UnregisterEffect(MIX_CHANNEL_POST, noEffect));
// you may print Mix_GetError() if you want to check it.
// it should say "No such effect registered" after this loop.

See Also:
4.6.3 Mix_UnregisterAllEffects, 4.6.1 Mix_RegisterEffect

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_UnregisterAllEffects

4.6.3 Mix_UnregisterAllEffects

int Mix_UnregisterAllEffects(int channel)

channel
Channel to remove all effects from.
Use MIX_CHANNEL_POST for the postmix stream.

This removes all effects registered to channel. If the channel is active all the registered effects will have their Mix_EffectDone_t functions called, if they were specified in Mix_RegisterEffect.

Returns: Zero on errors, such as channel not existing.

// remove all effects from channel 0
if(!Mix_UnregisterAllEffects(0)) {
    printf("Mix_UnregisterAllEffects: %s\n", Mix_GetError());
}

See Also:
4.6.2 Mix_UnregisterEffect, 4.6.1 Mix_RegisterEffect

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_SetPostMix

4.6.4 Mix_SetPostMix

void Mix_SetPostMix(void (*mix_func)(void *udata, Uint8 *stream, int len),
                    void *arg)

mix_func
The function pointer for the postmix processor.
NULL unregisters the current postmixer.
arg
A pointer to data to pass into the mix_func's udata parameter. It is a good place to keep the state data for the processor, especially if the processor is made to handle multiple channels at the same time.
This may be NULL, depending on the processor.

Hook a processor function mix_func to the postmix stream for post processing effects. You may just be reading the data and displaying it, or you may be altering the stream to add an echo. Most processors also have state data that they allocate as they are in use, this would be stored in the arg pointer data space. This processor is never really finished, until the audio device is closed, or you pass NULL as the mix_func.
There can only be one postmix function used at a time through this method. Use Mix_RegisterEffect(MIX_CHANNEL_POST, mix_func, NULL, arg) to use multiple postmix processors.
This postmix processor is run AFTER all the registered postmixers set up by Mix_RegisterEffect.

// make a passthru processor function that does nothing...
void noEffect(void *udata, Uint8 *stream, int len)
{
    // you could work with stream here...
}
...
// register noEffect as a postmix processor
Mix_SetPostMix(noEffect, NULL);

See Also:
4.6.1 Mix_RegisterEffect

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_SetPanning

4.6.5 Mix_SetPanning

int Mix_SetPanning(int channel, Uint8 left, Uint8 right)

channel
Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream.
left
Volume for the left channel, range is 0(silence) to 255(loud)
right
Volume for the left channel, range is 0(silence) to 255(loud)

This effect will only work on stereo audio. Meaning you called Mix_OpenAudio with 2 channels (MIX_DEFAULT_CHANNELS). The easiest way to do true panning is to call Mix_SetPanning(channel, left, 254 - left); so that the total volume is correct, if you consider the maximum volume to be 127 per channel for center, or 254 max for left, this works, but about halves the effective volume.
This Function registers the effect for you, so don't try to Mix_RegisterEffect it yourself.
NOTE: Setting both left and right to 255 will unregister the effect from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.
NOTE: Using this function on a mono audio device will not register the effect, nor will it return an error status.

Returns: Zero on errors, such as bad channel, or if Mix_RegisterEffect failed.

// pan channel 1 halfway to the left
if(!Mix_SetPanning(1, 255, 127)) {
    printf("Mix_SetPanning: %s\n", Mix_GetError());
    // no panning, is it ok?
}

See Also:
4.6.7 Mix_SetPosition, 4.6.3 Mix_UnregisterAllEffects

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_SetDistance

4.6.6 Mix_SetDistance

int Mix_SetDistance(int channel, Uint8 distance)

channel
Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream.
distance
Specify the distance from the listener, from 0(close/loud) to 255(far/quiet).

This effect simulates a simple attenuation of volume due to distance. The volume never quite reaches silence, even at max distance.
NOTE: Using a distance of 0 will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.

Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect failed.

// distance channel 1 to be farthest away
if(!Mix_SetDistance(1, 255)) {
    printf("Mix_SetDistance: %s\n", Mix_GetError());
    // no distance, is it ok?
}

See Also:
4.6.7 Mix_SetPosition, 4.6.3 Mix_UnregisterAllEffects

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_SetPosition

4.6.7 Mix_SetPosition

int Mix_SetPosition(int channel, Sint16 angle, Uint8 distance)

channel
Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream.
angle
Direction in relation to forward from 0 to 360 degrees. Larger angles will be reduced to this range using angles % 360.
0 = directly in front.
90 = directly to the right.
180 = directly behind.
270 = directly to the left.
So you can see it goes clockwise starting at directly in front.
This ends up being similar in effect to Mix_SetPanning.
distance
The distance from the listener, from 0(near/loud) to 255(far/quiet).
This is the same as the Mix_SetDistance effect.

This effect emulates a simple 3D audio effect. It's not all that realistic, but it can help improve some level of realism. By giving it the angle and distance from the camera's point of view, the effect pans and attenuates volumes. If you are looking for better positional audio, using OpenAL is suggested.
NOTE: Using angle and distance of 0, will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.

Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect failed.

// set channel 2 to be behind and right, and 100 units away
if(!Mix_SetPosition(2, 135, 100)) {
    printf("Mix_SetPosition: %s\n", Mix_GetError());
    // no position effect, is it ok?
}

See Also:
4.6.5 Mix_SetPanning, 4.6.6 Mix_SetDistance, 4.6.3 Mix_UnregisterAllEffects

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_SetReverseStereo

4.6.8 Mix_SetReverseStereo

int Mix_SetReverseStereo(int channel, int flip)

channel
Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream.
flip
Must be non-zero to work, means nothing to the effect processor itself.
set to zero to unregister the effect from channel.

Simple reverse stereo, swaps left and right channel sound.
NOTE: Using a flip of 0, will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.

Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect failed.

// set the total mixer output to be reverse stereo
if(!Mix_SetReverseStereo(MIX_CHANNEL_POST, 1)) {
    printf("Mix_SetReverseStereo: %s\n", Mix_GetError());
    // no reverse stereo, is it ok?
}

See Also:
4.6.3 Mix_UnregisterAllEffects

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Types

5. Types

These types are defined and used by the SDL_mixer API.

5.1 Mix_Chunk | The internal format for an audio chunk
5.2 Mix_Music | The internal format for a music chunk
5.3 Mix_MusicType | Music type enumerations
5.4 Mix_Fading | Fader effect type enumerations
5.5 Mix_EffectFunc_t | Special effect callback function pointer
5.6 Mix_EffectDone_t | Special effect done callback function pointer

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_Chunk

5.1 Mix_Chunk

typedef struct {
    int allocated;
    Uint8 *abuf;
    Uint32 alen;
    Uint8 volume;     /* Per-sample volume, 0-128 */
} Mix_Chunk;

allocated
a boolean indicating whether to free abuf when the chunk is freed.
0 if the memory was not allocated and thus not owned by this chunk.
1 if the memory was allocated and is thus owned by this chunk.
abuf
Pointer to the sample data.
alen
Length of abuf in bytes.
volume
0 = silent, 128 = max volume. This takes effect when mixing.

The internal format for an audio chunk. This stores the sample data, the length in bytes of that data, and the volume to use when mixing the sample.

See Also:
4.2.5 Mix_VolumeChunk, 4.3.16 Mix_GetChunk, 4.2.1 Mix_LoadWAV, 4.2.2 Mix_LoadWAV_RW, 4.2.6 Mix_FreeChunk, 5.2 Mix_Music

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_Music

5.2 Mix_Music

typedef struct _Mix_Music Mix_Music;

This is an opaque data type used for Music data. This should always be used as a pointer. Who knows why it isn't a pointer in this typedef...

See Also:
4.5.1 Mix_LoadMUS, 4.5.2 Mix_FreeMusic, 5.1 Mix_Chunk

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_MusicType

5.3 Mix_MusicType

typedef enum {
    MUS_NONE,
    MUS_CMD,
    MUS_WAV,
    MUS_MOD,
    MUS_MID,
    MUS_OGG,
    MUS_MP3
} Mix_MusicType;

Return values from Mix_GetMusicType are of these enumerated values.
If no music is playing then MUS_NONE is returned.
If music is playing via an external command then MUS_CMD is returned.
Otherwise they are self explanatory.

See Also:
4.5.16 Mix_GetMusicType

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_Fading

5.4 Mix_Fading

typedef enum {
    MIX_NO_FADING,
    MIX_FADING_OUT,
    MIX_FADING_IN
} Mix_Fading;

Return values from Mix_FadingMusic and Mix_FadingChannel are of these enumerated values. If no fading is taking place on the queried channel or music, then MIX_NO_FADING is returned. Otherwise they are self explanatory.

See Also:
4.3.15 Mix_FadingChannel, 4.5.19 Mix_FadingMusic

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_EffectFunc_t

5.5 Mix_EffectFunc_t

typedef void (*Mix_EffectFunc_t)(int chan, void *stream, int len,
                                 void *udata);

chan
The channel number that this effect is effecting now.
MIX_CHANNEL_POST is passed in for post processing effects over the final mix.
stream
The buffer containing the current sample to process.
len
The length of stream in bytes.
udata
User data pointer that was passed in to Mix_RegisterEffect when registering this effect processor function.

This is the prototype for effect processing functions. These functions are used to apply effects processing on a sample chunk. As a channel plays a sample, the registered effect functions are called. Each effect would then read and perhaps alter the len bytes of stream. It may also be advantageous to keep the effect state in the udata, with would be setup when registering the effect function on a channel.

See Also:
4.6.1 Mix_RegisterEffect 4.6.2 Mix_UnregisterEffect

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Mix_EffectDone_t

5.6 Mix_EffectDone_t

typedef void (*Mix_EffectDone_t)(int chan, void *udata);

chan
The channel number that this effect is effecting now.
MIX_CHANNEL_POST is passed in for post processing effects over the final mix.
udata
User data pointer that was passed in to Mix_RegisterEffect when registering this effect processor function.

This is the prototype for effect processing functions. This is called when a channel has finished playing, or halted, or is deallocated. This is also called when a processor is unregistered while processing is active. At that time the effects processing function may want to reset some internal variables or free some memory. It should free memory at least, because the processor could be freed after this call.

See Also:
4.6.1 Mix_RegisterEffect 4.6.2 Mix_UnregisterEffect

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Defines

6. Defines

MIX_MAJOR_VERSION
1
SDL_mixer library major number at compilation time
MIX_MINOR_VERSION
2
SDL_mixer library minor number at compilation time
MIX_PATCHLEVEL
4
SDL_mixer library patch level at compilation time
MIX_CHANNELS
8
The default mixer has this many simultaneous mixing channels after the first call to Mix_OpenAudio.
MIX_DEFAULT_FREQUENCY
22050
Good default sample rate in Hz (samples per second) for PC sound cards.
MIX_DEFAULT_FORMAT
AUDIO_S16SYS
The suggested default is signed 16bit samples in host byte order.
MIX_DEFAULT_CHANNELS
2
Stereo sound is a good default.
MIX_MAX_VOLUME
128
Maximum value for any volume setting.
This is currently the same as SDL_MIX_MAXVOLUME.
MIX_CHANNEL_POST
-2
This is the channel number used for post processing effects.
MIX_EFFECTSMAXSPEED
"MIX_EFFECTSMAXSPEED"
A convience definition for the string name of the environment variable to define when you desire the internal effects to sacrifice quality and/or RAM for speed. The environment variable must be set (else nonexisting) before Mix_OpenAudio is called for the setting to take effect.

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Glossary

7. Glossary

Byte Order
Also known as Big-Endian. Which means the most significant byte comes first in storage. Sparc and Motorola 68k based chips are MSB ordered.
(SDL defines this as SDL_BYTEORDER==SDL_BIG_ENDIAN)

Little-Endian(LSB) is stored in the opposite order, with the least significant byte first in memory. Intel and AMD are two LSB machines.
(SDL defines this as SDL_BYTEORDER==SDL_LIL_ENDIAN)

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.4: Index

Index

Jump to: B L M R S

 | Index Entry | Section
B |  |
 | Big-Endian | 7. Glossary
 | Byte Order | 7. Glossary
L |  |
 | Little-Endian | 7. Glossary
 | LSB | 7. Glossary
M |  |
 | Mix_AllocateChannels | 4.3.1 Mix_AllocateChannels
 | MIX_CHANNEL_POST | 6. Defines
 | Mix_ChannelFinished | 4.3.12 Mix_ChannelFinished
 | MIX_CHANNELS | 6. Defines
 | Mix_Chunk | 4.2 Samples
 | Mix_Chunk | 5.1 Mix_Chunk
 | Mix_CloseAudio | 4.1.3 Mix_CloseAudio
 | MIX_DEFAULT_CHANNELS | 6. Defines
 | MIX_DEFAULT_FORMAT | 6. Defines
 | MIX_DEFAULT_FREQUENCY | 6. Defines
 | Mix_EffectDone_t | 5.6 Mix_EffectDone_t
 | Mix_EffectFunc_t | 5.5 Mix_EffectFunc_t
 | MIX_EFFECTSMAXSPEED | 6. Defines
 | Mix_ExpireChannel | 4.3.10 Mix_ExpireChannel
 | Mix_FadeInChannel | 4.3.5 Mix_FadeInChannel
 | Mix_FadeInChannel | 4.4.1 Mix_ReserveChannels
 | Mix_FadeInChannelTimed | 4.3.6 Mix_FadeInChannelTimed
 | Mix_FadeInChannelTimed | 4.4.1 Mix_ReserveChannels
 | Mix_FadeInMusic | 4.5.4 Mix_FadeInMusic
 | Mix_FadeInMusicPos | 4.5.5 Mix_FadeInMusicPos
 | Mix_FadeOutChannel | 4.3.11 Mix_FadeOutChannel
 | Mix_FadeOutGroup | 4.4.8 Mix_FadeOutGroup
 | Mix_FadeOutMusic | 4.5.14 Mix_FadeOutMusic
 | Mix_Fading | 5.4 Mix_Fading
 | Mix_FadingChannel | 4.3.15 Mix_FadingChannel
 | Mix_FadingMusic | 4.5.19 Mix_FadingMusic
 | Mix_FreeChunk | 4.2.6 Mix_FreeChunk
 | Mix_FreeMusic | 4.5.2 Mix_FreeMusic
 | Mix_GetChunk | 4.3.16 Mix_GetChunk
 | Mix_GetError | 4.1.5 Mix_GetError
 | Mix_GetMusicHookData | 4.5.20 Mix_GetMusicHookData
 | Mix_GetMusicType | 4.5.16 Mix_GetMusicType
 | Mix_GroupAvailable | 4.4.5 Mix_GroupAvailable
 | Mix_GroupChannel | 4.4.2 Mix_GroupChannel
 | Mix_GroupChannels | 4.4.3 Mix_GroupChannels
 | Mix_GroupCount | 4.4.4 Mix_GroupCount
 | Mix_GroupNewer | 4.4.7 Mix_GroupNewer
 | Mix_GroupOldest | 4.4.6 Mix_GroupOldest
 | Mix_HaltChannel | 4.3.9 Mix_HaltChannel
 | Mix_HaltGroup | 4.4.9 Mix_HaltGroup
 | Mix_HaltMusic | 4.5.13 Mix_HaltMusic
 | Mix_HookMusic | 4.5.6 Mix_HookMusic
 | Mix_HookMusicFinished | 4.5.15 Mix_HookMusicFinished
 | Mix_Linked_Version | 4.1.1 Mix_Linked_Version
 | Mix_LoadMUS | 4.5.1 Mix_LoadMUS
 | Mix_LoadWAV | 4.2.1 Mix_LoadWAV
 | Mix_LoadWAV_RW | 4.2.2 Mix_LoadWAV_RW
 | MIX_MAJOR_VERSION | 6. Defines
 | MIX_MAX_VOLUME | 6. Defines
 | MIX_MINOR_VERSION | 6. Defines
 | Mix_Music | 5.2 Mix_Music
 | Mix_MusicType | 5.3 Mix_MusicType
 | Mix_OpenAudio | 4.1.2 Mix_OpenAudio
 | MIX_PATCHLEVEL | 6. Defines
 | Mix_Pause | 4.3.7 Mix_Pause
 | Mix_Paused | 4.3.14 Mix_Paused
 | Mix_PausedMusic | 4.5.18 Mix_PausedMusic
 | Mix_PauseMusic | 4.5.8 Mix_PauseMusic
 | Mix_PlayChannel | 4.3.3 Mix_PlayChannel
 | Mix_PlayChannel | 4.4.1 Mix_ReserveChannels
 | Mix_PlayChannelTimed | 4.3.4 Mix_PlayChannelTimed
 | Mix_PlayChannelTimed | 4.4.1 Mix_ReserveChannels
 | Mix_Playing | 4.3.13 Mix_Playing
 | Mix_PlayingMusic | 4.5.17 Mix_PlayingMusic
 | Mix_PlayMusic | 4.5.3 Mix_PlayMusic
 | Mix_QuerySpec | 4.1.6 Mix_QuerySpec
 | Mix_QuickLoad_RAW | 4.2.4 Mix_QuickLoad_RAW
 | Mix_QuickLoad_WAV | 4.2.3 Mix_QuickLoad_WAV
 | Mix_RegisterEffect | 4.6.1 Mix_RegisterEffect
 | Mix_ReserveChannels | 4.4.1 Mix_ReserveChannels
 | Mix_Resume | 4.3.8 Mix_Resume
 | Mix_ResumeMusic | 4.5.9 Mix_ResumeMusic
 | Mix_RewindMusic | 4.5.10 Mix_RewindMusic
 | Mix_SetDistance | 4.6.6 Mix_SetDistance
 | Mix_SetError | 4.1.4 Mix_SetError
 | Mix_SetMusicCMD | 4.5.12 Mix_SetMusicCMD
 | Mix_SetMusicPosition | 4.5.11 Mix_SetMusicPosition
 | Mix_SetPanning | 4.6.5 Mix_SetPanning
 | Mix_SetPosition | 4.6.7 Mix_SetPosition
 | Mix_SetPostMix | 4.6.4 Mix_SetPostMix
 | Mix_SetReverseStereo | 4.6.8 Mix_SetReverseStereo
 | Mix_UnregisterAllEffects | 4.6.3 Mix_UnregisterAllEffects
 | Mix_UnregisterEffect | 4.6.2 Mix_UnregisterEffect
 | MIX_VERSION | 4.1.1 Mix_Linked_Version
 | Mix_Volume | 4.3.2 Mix_Volume
 | Mix_VolumeChunk | 4.2.5 Mix_VolumeChunk
 | Mix_VolumeMusic | 4.5.7 Mix_VolumeMusic
 | MSB | 7. Glossary
R |  |
 | README | 1. Overview
S |  |
 | sdl-config | 2.2 Compiling
 | SDL_AudioDriverName | 3. Conflicts
 | SDL_CloseAudio | 3. Conflicts
 | SDL_GetAudioStatus | 3. Conflicts
 | SDL_LockAudio | 3. Conflicts
 | SDL_OpenAudio | 3. Conflicts
 | SDL_PauseAudio | 3. Conflicts
 | SDL_UnlockAudio | 3. Conflicts

Jump to: B L M R S

This document was generated on November, 1 2002 using texi2html


SDL_image 1.2.8: About this document

About this document

This document was generated on November, 3 2009 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8: Short Table of Contents

Short Table of Contents

1. Overview
2. Getting Started
3. Functions
4. Defines
Index

This document was generated on November, 3 2009 using texi2html


SDL_image 1.2.8:

Content

1. Overview
2. Getting Started
3. Functions
4. Defines
Index


SDL_mixer 1.2.10: SDL_mixer 1.2.10

SDL_mixer 1.2.10

1. Overview The README from the SDL_mixer distribution

2. Getting Started Using SDL_mixer

3. Conflicts Conflicts with SDL Audio functions

4. Functions | Functions supported by the SDL_mixer API
5. Types | Types used with the SDL_mixer API
6. Defines | Defined values/macros in the SDL_mixer API

7. Glossary Terms used in this document

Index Index of selected words

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Overview

1. Overview

A Little Bit About Me

I am currently, as I write this document, a programmer for Raytheon. There I do all sorts of communications, network, GUI, and other general programming tasks in C/C++ on the Solaris and sometimes Linux Operating Systems. I have been programming sound code in my free time for only a little while now. Sound is an integral part to any game. The human senses are mostly starved during video game play. there's only some tactile feedback on some controlers, and of course the eyes are in use but only for about 30% of their viewing area. So to add more we do need sound to help the game player feel more in the action, and to set certain moods as the game progresses. Sound ends up accounting for perhaps 50% or more of a gamers experience. Music and sound effects are all integral parts of the gaming experience. While this document doesn't explain how to get music and samples to use, it will explain how to use them with SDL_mixer.

Feel free to contact me: JonathanCAtkins@gmail.com

I am also usually on IRC at irc.freenode.net in the #SDL channel as LIM

This is the README in the SDL_mixer source archive.

SDL_mixer 1.2

The latest version of this library is available from:
SDL_mixer Homepage

Due to popular demand, here is a simple multi-channel audio mixer. It supports 8 channels of 16 bit stereo audio, plus a single channel of music, mixed by the popular MikMod MOD, Timidity MIDI and SMPEG MP3 libraries.

See the header file SDL_mixer.h and the examples playwave.c and playmus.c for documentation on this mixer library.

The mixer can currently load Microsoft WAVE files and Creative Labs VOC files as audio samples, and can load MIDI files via Timidity and the following music formats via MikMod: .MOD .S3M .IT .XM. It can load Ogg Vorbis streams as music if built with the Ogg Vorbis libraries, and finally it can load MP3 music using the SMPEG library.

The process of mixing MIDI files to wave output is very CPU intensive, so if playing regular WAVE files sound great, but playing MIDI files sound choppy, try using 8-bit audio, mono audio, or lower frequencies.

To play MIDI files, you'll need to get a complete set of GUS patches from: Timidity GUS Patches and unpack them in /usr/local/lib under UNIX, and C:\ under Win32.

This library is available under the GNU Library General Public License, see the file "COPYING" for details.

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Getting Started

2. Getting Started

This assumes you have gotten SDL_mixer and installed it on your system. SDL_mixer has an INSTALL document in the source distribution to help you get it compiled and installed.

Generally, installation consists of:

./configure
make
make install

SDL_mixer supports playing music and sound samples from the following formats:
- WAVE/RIFF (.wav)
- AIFF (.aiff)
- VOC (.voc)
- MOD (.mod .xm .s3m .669 .it .med and more) requiring libmikmod on system
- MIDI (.mid) using timidity or native midi hardware
- OggVorbis (.ogg) requiring ogg/vorbis libraries on system
- MP3 (.mp3) requiring SMPEG or MAD library on system
- FLAC (.flac) requiring the FLAC library on system - also any command-line player, which is not mixed by SDL_mixer...

You may also want to look at some demonstration code which may be downloaded from:
http://www.jonatkins.org/SDL_mixer/

2.1 Includes | The include files to use for SDL_mixer
2.2 Compiling | Using the SDL_mixer library and header file.

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Includes

2.1 Includes

To use SDL_mixer functions in a C/C++ source code file, you must use the SDL_mixer.h include file:

#include "SDL_mixer.h"

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Compiling

2.2 Compiling

To link with SDL_mixer you should use sdl-config to get the required SDL compilation options. After that, compiling with SDL_mixer is quite easy.
Note: Some systems may not have the SDL_mixer library and include file in the same place as the SDL library and includes are located, in that case you will need to add more -I and -L paths to these command lines.

Simple Example for compiling an object file:

cc -c `sdl-config --cflags` mysource.c

Simple Example for compiling an object file:

cc -o myprogram mysource.o `sdl-config --libs` -lSDL_mixer

Now myprogram is ready to run.

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Conflicts

3. Conflicts

When using SDL_mixer functions you need to avoid the following functions from SDL:

SDL_OpenAudio
Use Mix_OpenAudio instead.
SDL_CloseAudio
Use Mix_CloseAudio instead.
SDL_PauseAudio
Use Mix_Pause(-1) and Mix_PauseMusic instead, to pause.
Use Mix_Resume(-1) and Mix_ResumeMusic instead, to unpause.
SDL_LockAudio
This is just not needed since SDL_mixer handles this for you.
Using it may cause problems as well.
SDL_UnlockAudio
This is just not needed since SDL_mixer handles this for you.
Using it may cause problems as well.

You may call the following functions freely:

SDL_AudioDriverName
This will still work as usual.
SDL_GetAudioStatus
This will still work, though it will likely return SDL_AUDIO_PLAYING even though SDL_mixer is just playing silence.

It is also a BAD idea to call SDL_mixer and SDL audio functions from a callback. Callbacks include Effects functions and other SDL_mixer audio hooks.

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Functions

4. Functions

These are the functions in the SDL_mixer API.

4.1 General | API activation
4.2 Samples | Loading sounds from files or memory
4.3 Channels | Sound effect channels
4.4 Groups | Sound effect channel grouping
4.5 Music | Music playing
4.6 Effects | Special effects processing

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: General

4.1 General

These functions are useful, as they are the only/best ways to work with SDL_mixer.

Info
4.1.1 Mix_Linked_Version Get version number
Activation
4.1.2 Mix_Init | Initialize SDL_mixer
4.1.3 Mix_Quit | Cleanup SDL_mixer
4.1.4 Mix_OpenAudio | Open sound mixer
4.1.5 Mix_CloseAudio | Close sound mixer
Errors
4.1.6 Mix_SetError | Set the current error string
4.1.7 Mix_GetError | Get the current error string
Settings
4.1.8 Mix_QuerySpec Get output format

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_Linked_Version

4.1.1 Mix_Linked_Version

const SDL_version *Mix_Linked_Version()
void SDL_MIXER_VERSION(SDL_version *compile_version)

This works similar to SDL_Linked_Version and SDL_VERSION.
Using these you can compare the runtime version to the version that you compiled with.

SDL_version compile_version;
const SDL_version *link_version=Mix_Linked_Version();
SDL_MIXER_VERSION(&compile_version);
printf("compiled with SDL_mixer version: %d.%d.%d\n",
        compile_version.major,
        compile_version.minor,
        compile_version.patch);
printf("running with SDL_mixer version: %d.%d.%d\n",
        link_version->major,
        link_version->minor,
        link_version->patch);

See Also:
4.1.4 Mix_OpenAudio, 4.1.8 Mix_QuerySpec

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_Init

4.1.2 Mix_Init

int Mix_Init(int flags)

flags
bitwise OR'd set of sample/music formats to support by loading a library now. The values you may OR together to pass in are:
MIX_INIT_FLAC
MIX_INIT_MOD
MIX_INIT_MP3
MIX_INIT_OGG

Initialize by loading support as indicated by the flags, or at least return success if support is already loaded. You may call this multiple times, which will actually require you to call Mix_Quit just once to clean up. You may call this function with a 0 to retrieve whether support was built-in or not loaded yet.
Note: you can call Mix_Init with the right MIX_INIT_* flags OR'd together before you program gets busy, to prevent a later hiccup while it loads and unloads the library, and to check that you do have the support that you need before you try and use it.
Note: this function does not always set the error string, so do not depend on Mix_GetError being meaningful all the time.

Returns: a bitmask of all the currently initted sample/music loaders.

// load support for the OGG and MOD sample/music formats
int flags=MIX_INIT_OGG|MIX_INIT_MOD;
int initted=Mix_Init(flags);
if(initted&flags != flags) {
    printf("Mix_Init: Failed to init required ogg and mod support!\n");
    printf("Mix_Init: %s\n", Mix_GetError());
    // handle error
}

See Also:
4.1.3 Mix_Quit

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_Quit

4.1.3 Mix_Quit

void Mix_Quit()

This function cleans up all dynamically loaded library handles, freeing memory. If support is required again it will be initialized again, either by Mix_Init or loading a sample or some music with dynamic support required. You may call this function when Mix_Load functions are no longer needed for the MIX_INIT_* formats. You should call this function for each time Mix_Init was called, otherwise it may not free all the dynamic library resources until the program ends. This is done so that multiple unrelated modules of a program may call Mix_Init and Mix_Quit without affecting the others performance and needs.

// indicate that we are ready to unload the dynamically loaded libraries
Mix_Quit();

NOTE: Since each call to Mix_Init may set different flags, there is no way, currently, to request how many times each one was initted. In other words, the only way to quit for sure is to do a loop like so:
// force a quit
while(Mix_Init(0))
    Mix_Quit();

See Also:
4.1.2 Mix_Init

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_OpenAudio

4.1.4 Mix_OpenAudio

int Mix_OpenAudio(int frequency, Uint16 format, int channels, int chunksize)

frequency
Output sampling frequency in samples per second (Hz).
you might use MIX_DEFAULT_FREQUENCY(22050) since that is a good value for most games.
format
Output sample format.
channels
Number of sound channels in output.
Set to 2 for stereo, 1 for mono. This has nothing to do with mixing channels.
chunksize
Bytes used per output sample.

Initialize the mixer API.
This must be called before using other functions in this library.
SDL must be initialized with SDL_INIT_AUDIO before this call. frequency would be 44100 for 44.1KHz, which is CD audio rate. Most games use 22050, because 44100 requires too much CPU power on older computers. chunksize is the size of each mixed sample. The smaller this is the more your hooks will be called. If make this too small on a slow system, sound may skip. If made to large, sound effects will lag behind the action more. You want a happy medium for your target computer. You also may make this 4096, or larger, if you are just playing music. MIX_CHANNELS(8) mixing channels will be allocated by default. You may call this function multiple times, however you will have to call Mix_CloseAudio just as many times for the device to actually close. The format will not changed on subsequent calls until fully closed. So you will have to close all the way before trying to open with different format parameters.

format is based on SDL audio support, see SDL_audio.h. Here are the values listed there:

AUDIO_U8
Unsigned 8-bit samples
AUDIO_S8
Signed 8-bit samples
AUDIO_U16LSB
Unsigned 16-bit samples, in little-endian byte order
AUDIO_S16LSB
Signed 16-bit samples, in little-endian byte order
AUDIO_U16MSB
Unsigned 16-bit samples, in big-endian byte order
AUDIO_S16MSB
Signed 16-bit samples, in big-endian byte order
AUDIO_U16
same as AUDIO_U16LSB (for backwards compatability probably)
AUDIO_S16
same as AUDIO_S16LSB (for backwards compatability probably)
AUDIO_U16SYS
Unsigned 16-bit samples, in system byte order
AUDIO_S16SYS
Signed 16-bit samples, in system byte order

MIX_DEFAULT_FORMAT is the same as AUDIO_S16SYS.

Returns: 0 on success, -1 on errors

// start SDL with audio support
if(SDL_Init(SDL_INIT_AUDIO)==-1) {
    printf("SDL_Init: %s\n", SDL_GetError());
    exit(1);
}
// open 44.1KHz, signed 16bit, system byte order,
//      stereo audio, using 1024 byte chunks
if(Mix_OpenAudio(44100, MIX_DEFAULT_FORMAT, 2, 1024)==-1) {
    printf("Mix_OpenAudio: %s\n", Mix_GetError());
    exit(2);
}

See Also:
4.1.5 Mix_CloseAudio, 4.1.8 Mix_QuerySpec, 4.3.1 Mix_AllocateChannels

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_CloseAudio

4.1.5 Mix_CloseAudio

void Mix_CloseAudio()

Shutdown and cleanup the mixer API.
After calling this all audio is stopped, the device is closed, and the SDL_mixer functions should not be used. You may, of course, use Mix_OpenAudio to start the functionality again.
Note: This function doesn't do anything until you have called it the same number of times that you called Mix_OpenAudio. You may use Mix_QuerySpec to find out how many times Mix_CloseAudio needs to be called before the device is actually closed.

Mix_CloseAudio();
// you could SDL_Quit(); here...or not.

See Also:
4.1.4 Mix_OpenAudio, 4.1.8 Mix_QuerySpec

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_SetError

4.1.6 Mix_SetError

void Mix_SetError(const char *fmt, ...)

This is the same as SDL_SetError, which sets the error string which may be fetched with Mix_GetError (or SDL_GetError). This functions acts like printf, except that it is limited to SDL_ERRBUFIZE(1024) chars in length. It only accepts the following format types: %s, %d, %f, %p. No variations are supported, like %.2f would not work. For any more specifics read the SDL docs.

int mymixfunc(int i) {
    Mix_SetError("mymixfunc is not implemented! %d was passed in.",i);
    return(-1);
}

See Also:
4.1.7 Mix_GetError

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_GetError

4.1.7 Mix_GetError

char *Mix_GetError()

This is the same as SDL_GetError, which returns the last error set as a string which you may use to tell the user what happened when an error status has been returned from an SDL_mixer function call.

Returns: a char pointer (string) containing a humam readble version or the reason for the last error that occured.

printf("Oh My Goodness, an error : %s", Mix_GetError());

See Also:
4.1.6 Mix_SetError

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_QuerySpec

4.1.8 Mix_QuerySpec

int Mix_QuerySpec(int *frequency, Uint16 *format, int *channels)

frequency
A pointer to an int where the frequency actually used by the opened audio device will be stored.
format
A pointer to a Uint16 where the output format actually being used by the audio device will be stored.
channels
A pointer to an int where the number of audio channels will be stored.
2 will mean stereo, 1 will mean mono.

Get the actual audio format in use by the opened audio device. This may or may not match the parameters you passed to Mix_OpenAudio.

Returns: 0 on error. If the device was open the number of times it was opened will be returned. The values of the arguments variables are not set on an error.

// get and print the audio format in use
int numtimesopened, frequency, channels;
Uint16 format;
numtimesopened=Mix_QuerySpec(&frequency, &format, &channels);
if(!numtimesopened) {
    printf("Mix_QuerySpec: %s\n",Mix_GetError());
}
else {
    char *format_str="Unknown";
    switch(format) {
        case AUDIO_U8: format_str="U8"; break;
        case AUDIO_S8: format_str="S8"; break;
        case AUDIO_U16LSB: format_str="U16LSB"; break;
        case AUDIO_S16LSB: format_str="S16LSB"; break;
        case AUDIO_U16MSB: format_str="U16MSB"; break;
        case AUDIO_S16MSB: format_str="S16MSB"; break;
    }
    printf("opened=%d times  frequency=%dHz  format=%s  channels=%d",
            numtimesopened, frequency, format_str, channels);
}

See Also:
4.1.4 Mix_OpenAudio

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Samples

4.2 Samples

These functions work with Mix_Chunk samples.

Loading
4.2.1 Mix_GetNumChunkDecoders | Number of sample format types that can be decoded
4.2.2 Mix_GetChunkDecoder | Name of enumerated sample format type decoder
4.2.3 Mix_LoadWAV | From a file
4.2.4 Mix_LoadWAV_RW | Using RWops
4.2.5 Mix_QuickLoad_WAV | From memory, in output format already
4.2.6 Mix_QuickLoad_RAW | From memory, in output format already
Settings
4.2.7 Mix_VolumeChunk Set mix volume
Freeing
4.2.8 Mix_FreeChunk Free sample

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_GetNumChunkDecoders

4.2.1 Mix_GetNumChunkDecoders

int Mix_GetNumChunkDecoders()

Get the number of sample chunk decoders available from the Mix_GetChunkDecoder function. This number can be different for each run of a program, due to the change in availability of shared libraries that support each format.

Returns: The number of sample chunk decoders available.

// print the number of sample chunk decoders available
printf("There are %d sample chunk deocoders available\n", Mix_GetNumChunkDecoders());

See Also:
4.5.1 Mix_GetNumMusicDecoders, 4.2.2 Mix_GetChunkDecoder, 4.2.3 Mix_LoadWAV

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_GetChunkDecoder

4.2.2 Mix_GetChunkDecoder

const char *Mix_GetChunkDecoder(int index)

index
The index number of sample chunk decoder to get.
In the range from 0(zero) to Mix_GetNumChunkDecoders()-1, inclusive.

Get the name of the indexed sample chunk decoder. You need to get the number of sample chunk decoders available using the Mix_GetNumChunkDecoders function.

Returns: The name of the indexed sample chunk decoder. This string is owned by the SDL_mixer library, do not modify or free it. It is valid until you call Mix_CloseAudio the final time.

// print sample chunk decoders available
int i,max=Mix_GetNumChunkDecoders();
for(i=0; i<max; ++i)
    printf("Sample chunk decoder %d is for %s",Mix_GetChunkDecoder(i));

See Also:
4.2.1 Mix_GetNumChunkDecoders, 4.5.2 Mix_GetMusicDecoder, 4.2.3 Mix_LoadWAV

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_LoadWAV

4.2.3 Mix_LoadWAV

Mix_Chunk *Mix_LoadWAV(char *file)

file
File name to load sample from.

Load file for use as a sample. This is actually Mix_LoadWAV_RW(SDL_RWFromFile(file, "rb"), 1). This can load WAVE, AIFF, RIFF, OGG, and VOC files.
Note: You must call SDL_OpenAudio before this. It must know the output characteristics so it can convert the sample for playback, it does this conversion at load time.

Returns: a pointer to the sample as a Mix_Chunk. NULL is returned on errors.

// load sample.wav in to sample
Mix_Chunk *sample;
sample=Mix_LoadWAV("sample.wav");
if(!sample) {
    printf("Mix_LoadWAV: %s\n", Mix_GetError());
    // handle error
}

See Also:
4.2.4 Mix_LoadWAV_RW, 4.2.5 Mix_QuickLoad_WAV, 4.2.8 Mix_FreeChunk

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_LoadWAV_RW

4.2.4 Mix_LoadWAV_RW

Mix_Chunk *Mix_LoadWAV_RW(SDL_RWops *src, int freesrc)

src
The source SDL_RWops as a pointer. The sample is loaded from this.
freesrc
A non-zero value mean is will automatically close/free the src for you.

Load src for use as a sample. This can load WAVE, AIFF, RIFF, OGG, and VOC formats. Using SDL_RWops is not covered here, but they enable you to load from almost any source. Note: You must call SDL_OpenAudio before this. It must know the output characteristics so it can convert the sample for playback, it does this conversion at load time.

Returns: a pointer to the sample as a Mix_Chunk. NULL is returned on errors.

// load sample.wav in to sample
Mix_Chunk *sample;
sample=Mix_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1);
if(!sample) {
    printf("Mix_LoadWAV_RW: %s\n", Mix_GetError());
    // handle error
}

See Also:
4.2.3 Mix_LoadWAV, 4.2.5 Mix_QuickLoad_WAV, 4.2.8 Mix_FreeChunk

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_QuickLoad_WAV

4.2.5 Mix_QuickLoad_WAV

Mix_Chunk *Mix_QuickLoad_WAV(Uint8 *mem)

mem
Memory buffer containing a WAVE file in output format.

Load mem as a WAVE/RIFF file into a new sample. The WAVE in mem must be already in the output format. It would be better to use Mix_LoadWAV_RW if you aren't sure.
Note: This function does very little checking. If the format mismatches the output format, or if the buffer is not a WAVE, it will not return an error. This is probably a dangerous function to use.

Returns: a pointer to the sample as a Mix_Chunk. NULL is returned on errors.

// quick-load a wave from memory
// Uint8 *wave; // I assume you have the wave loaded raw,
                // or compiled in the program...
Mix_Chunk *wave_chunk;
if(!(wave_chunk=Mix_QuickLoad_WAV(wave))) {
    printf("Mix_QuickLoad_WAV: %s\n", Mix_GetError());
    // handle error
}

See Also:
4.2.3 Mix_LoadWAV, 4.2.6 Mix_QuickLoad_RAW, 4.2.8 Mix_FreeChunk

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_QuickLoad_RAW

4.2.6 Mix_QuickLoad_RAW

Mix_Chunk *Mix_QuickLoad_RAW(Uint8 *mem)

mem
Memory buffer containing a WAVE file in output format.

Load mem as a raw sample. The data in mem must be already in the output format. If you aren't sure what you are doing, this is not a good function for you!
Note: This function does very little checking. If the format mismatches the output format it will not return an error. This is probably a dangerous function to use.

Returns: a pointer to the sample as a Mix_Chunk. NULL is returned on errors, such as when out of memory.

// quick-load a raw sample from memory
// Uint8 *raw; // I assume you have the raw data here,
                // or compiled in the program...
Mix_Chunk *raw_chunk;
if(!(raw_chunk=Mix_QuickLoad_RAW(raw))) {
    printf("Mix_QuickLoad_RAW: %s\n", Mix_GetError());
    // handle error
}

See Also:
4.2.3 Mix_LoadWAV, 4.2.5 Mix_QuickLoad_WAV, 4.2.8 Mix_FreeChunk

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_VolumeChunk

4.2.7 Mix_VolumeChunk

int Mix_VolumeChunk(Mix_Chunk *chunk, int volume)

chunk
Pointer to the Mix_Chunk to set the volume in.
volume
The volume to use from 0 to MIX_MAX_VOLUME(128).
If greater than MIX_MAX_VOLUME,
then it will be set to MIX_MAX_VOLUME.
If less than 0 then chunk->volume will not be set.

Set chunk->volume to volume.
The volume setting will take effect when the chunk is used on a channel, being mixed into the output.

Returns: previous chunk->volume setting. if you passed a negative value for volume then this volume is still the current volume for the chunk.

// set the sample's volume to 1/2
// Mix_Chunk *sample;
int previous_volume;
previous_volume=Mix_VolumeChunk(sample, MIX_MAX_VOLUME/2);
printf("previous_volume: %d\n", previous_volume);

See Also:
5.1 Mix_Chunk

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_FreeChunk

4.2.8 Mix_FreeChunk

void Mix_FreeChunk(Mix_Chunk *chunk)

chunk
Pointer to the Mix_Chunk to free.

Free the memory used in chunk, and free chunk itself as well. Do not use chunk after this without loading a new sample to it. Note: It's a bad idea to free a chunk that is still being played...

// free the sample
// Mix_Chunk *sample;
Mix_FreeChunk(sample);
sample=NULL; // to be safe...

See Also:
4.2.3 Mix_LoadWAV, 4.2.4 Mix_LoadWAV_RW, 4.2.5 Mix_QuickLoad_WAV,

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Channels

4.3 Channels

These functions work with sound effect mixer channels. Music is not affected by these functions.

Setup
4.3.1 Mix_AllocateChannels | Set the number of channels to mix
4.3.2 Mix_Volume | Set the mix volume of a channel
Playing
4.3.3 Mix_PlayChannel | Play loop
4.3.4 Mix_PlayChannelTimed | Play loop and limit by time
4.3.5 Mix_FadeInChannel | Play loop with fade in
4.3.6 Mix_FadeInChannelTimed | Play loop with fade in and limit by time
Pausing
4.3.7 Mix_Pause | Pause a channel
4.3.8 Mix_Resume | Resume a paused channel
Stopping
4.3.9 Mix_HaltChannel | Stop playing on a channel
4.3.10 Mix_ExpireChannel | Change the timed stoppage of a channel
4.3.11 Mix_FadeOutChannel | Stop playing channel after timed fade out
4.3.12 Mix_ChannelFinished | Set callback for when channel finishes playing
Info
4.3.13 Mix_Playing | Get the active playing status of a channel
4.3.14 Mix_Paused | Get the pause status of a channel
4.3.15 Mix_FadingChannel | Get the fade status of a channel
4.3.16 Mix_GetChunk | Get the sample playing on a channel

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_AllocateChannels

4.3.1 Mix_AllocateChannels

int Mix_AllocateChannels(int numchans)

numchans
Number of channels to allocate for mixing.
A negative number will not do anything, it will tell you how many channels are currently allocated.

Set the number of channels being mixed. This can be called multiple times, even with sounds playing. If numchans is less than the current number of channels, then the higher channels will be stopped, freed, and therefore not mixed any longer. It's probably not a good idea to change the size 1000 times a second though.
If any channels are deallocated, any callback set by Mix_ChannelFinished will be called when each channel is halted to be freed. Note: passing in zero WILL free all mixing channels, however music will still play.

Returns: The number of channels allocated. Never fails...but a high number of channels can segfault if you run out of memory. We're talking REALLY high!

// allocate 16 mixing channels
Mix_AllocateChannels(16);

See Also:
4.1.4 Mix_OpenAudio

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_Volume

4.3.2 Mix_Volume

int Mix_Volume(int channel, int volume)

channel
Channel to set mix volume for.
-1 will set the volume for all allocated channels.
volume
The volume to use from 0 to MIX_MAX_VOLUME(128).
If greater than MIX_MAX_VOLUME,
then it will be set to MIX_MAX_VOLUME.
If less than 0 then the volume will not be set.

Set the volume for any allocated channel. If channel is -1 then all channels at are set at once. The volume is applied during the final mix, along with the sample volume. So setting this volume to 64 will halve the output of all samples played on the specified channel. All channels default to a volume of 128, which is the max. Newly allocated channels will have the max volume set, so setting all channels volumes does not affect subsequent channel allocations.

Returns: current volume of the channel. If channel is -1, the average volume is returned.

// set channel 1 to half volume
Mix_Volume(1,MIX_MAX_VOLUME/2);

// print the average volume
printf("Average volume is %d\n",Mix_Volume(-1,-1));

See Also:
4.2.7 Mix_VolumeChunk, 4.5.9 Mix_VolumeMusic

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_PlayChannel

4.3.3 Mix_PlayChannel

int Mix_PlayChannel(int channel, Mix_Chunk *chunk, int loops)

channel
Channel to play on, or -1 for the first free unreserved channel.
chunk
Sample to play.
loops
Number of loops, -1 is infinite loops.
Passing one here plays the sample twice (1 loop).

Play chunk on channel, or if channel is -1, pick the first free unreserved channel. The sample will play for loops+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer.
Note: this just calls Mix_PlayChannelTimed() with ticks set to -1.

Returns: the channel the sample is played on. On any errors, -1 is returned.

// play sample on first free unreserved channel
// play it exactly once through
// Mix_Chunk *sample; //previously loaded
if(Mix_PlayChannel(-1, sample, 0)==-1) {
    printf("Mix_PlayChannel: %s\n",Mix_GetError());
    // may be critical error, or maybe just no channels were free.
    // you could allocated another channel in that case...
}

See Also:
4.3.4 Mix_PlayChannelTimed, 4.3.5 Mix_FadeInChannel, 4.3.9 Mix_HaltChannel, 4.3.10 Mix_ExpireChannel, 4.4.1 Mix_ReserveChannels

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_PlayChannelTimed

4.3.4 Mix_PlayChannelTimed

int Mix_PlayChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ticks)

channel
Channel to play on, or -1 for the first free unreserved channel.
chunk
Sample to play.
loops
Number of loops, -1 is infinite loops.
Passing one here plays the sample twice (1 loop).
ticks
Millisecond limit to play sample, at most.
If not enough loops or the sample chunk is not long enough, then the sample may stop before this timeout occurs.
-1 means play forever.

If the sample is long enough and has enough loops then the sample will stop after ticks milliseconds. Otherwise this function is the same as 4.3.3 Mix_PlayChannel.

Returns: the channel the sample is played on. On any errors, -1 is returned.

// play sample on first free unreserved channel
// play it for half a second
// Mix_Chunk *sample; //previously loaded
if(Mix_PlayChannelTimed(-1, sample, -1 , 500)==-1) {
    printf("Mix_PlayChannel: %s\n",Mix_GetError());
    // may be critical error, or maybe just no channels were free.
    // you could allocated another channel in that case...
}

See Also:
4.3.3 Mix_PlayChannel, 4.3.6 Mix_FadeInChannelTimed, 4.3.11 Mix_FadeOutChannel, 4.4.1 Mix_ReserveChannels

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_FadeInChannel

4.3.5 Mix_FadeInChannel

int Mix_FadeInChannel(int channel, Mix_Chunk *chunk, int loops, int ms)

channel
Channel to play on, or -1 for the first free unreserved channel.
chunk
Sample to play.
loops
Number of loops, -1 is infinite loops.
Passing one here plays the sample twice (1 loop).
ms
Milliseconds of time that the fade-in effect should take to go from silence to full volume.

Play chunk on channel, or if channel is -1, pick the first free unreserved channel.
The channel volume starts at 0 and fades up to full volume over ms milliseconds of time. The sample may end before the fade-in is complete if it is too short or doesn't have enough loops. The sample will play for loops+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer.
Note: this just calls Mix_FadeInChannelTimed() with ticks set to -1.

Returns: the channel the sample is played on. On any errors, -1 is returned.

// play sample on first free unreserved channel
// play it exactly 3 times through
// fade in over one second
// Mix_Chunk *sample; //previously loaded
if(Mix_FadeInChannel(-1, sample, 2, 1000)==-1) {
    printf("Mix_FadeInChannel: %s\n",Mix_GetError());
    // may be critical error, or maybe just no channels were free.
    // you could allocated another channel in that case...
}

See Also:
4.3.3 Mix_PlayChannel, 4.3.6 Mix_FadeInChannelTimed, 4.3.15 Mix_FadingChannel, 4.3.11 Mix_FadeOutChannel, 4.4.1 Mix_ReserveChannels

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_FadeInChannelTimed

4.3.6 Mix_FadeInChannelTimed

int Mix_FadeInChannelTimed(int channel, Mix_Chunk *chunk,
                           int loops, int ms, int ticks)

channel
Channel to play on, or -1 for the first free unreserved channel.
chunk
Sample to play.
loops
Number of loops, -1 is infinite loops.
Passing one here plays the sample twice (1 loop).
ms
Milliseconds of time that the fade-in effect should take to go from silence to full volume.
ticks
Millisecond limit to play sample, at most.
If not enough loops or the sample chunk is not long enough, then the sample may stop before this timeout occurs.
-1 means play forever.

If the sample is long enough and has enough loops then the sample will stop after ticks milliseconds. Otherwise this function is the same as 4.3.5 Mix_FadeInChannel.

Returns: the channel the sample is played on. On any errors, -1 is returned.

// play sample on first free unreserved channel
// play it for half a second
// Mix_Chunk *sample; //previously loaded
if(Mix_PlayChannelTimed(-1, sample, -1 , 500)==-1) {
    printf("Mix_PlayChannel: %s\n",Mix_GetError());
    // may be critical error, or maybe just no channels were free.
    // you could allocated another channel in that case...
}

See Also:
4.3.4 Mix_PlayChannelTimed, 4.3.5 Mix_FadeInChannel, 4.3.15 Mix_FadingChannel, 4.3.9 Mix_HaltChannel, 4.3.10 Mix_ExpireChannel, 4.4.1 Mix_ReserveChannels

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_Pause

4.3.7 Mix_Pause

void Mix_Pause(int channel)

channel
Channel to pause on, or -1 for all channels.

Pause channel, or all playing channels if -1 is passed in. You may still halt a paused channel.
Note: Only channels which are actively playing will be paused.

// pause all sample playback
Mix_Pause(-1);

See Also:
4.3.8 Mix_Resume, 4.3.14 Mix_Paused, 4.3.9 Mix_HaltChannel

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_Resume

4.3.8 Mix_Resume

void Mix_Resume(int channel)

channel
Channel to resume playing, or -1 for all channels.

Unpause channel, or all playing and paused channels if -1 is passed in.

// resume playback on all previously active channels
Mix_Resume(-1);

See Also:
4.3.7 Mix_Pause, 4.3.14 Mix_Paused

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_HaltChannel

4.3.9 Mix_HaltChannel

int Mix_HaltChannel(int channel)

channel
Channel to stop playing, or -1 for all channels.

Halt channel playback, or all channels if -1 is passed in.
Any callback set by Mix_ChannelFinished will be called.

Returns: always returns zero. (kinda silly)

// halt playback on all channels
Mix_HaltChannel(-1);

See Also:
4.3.10 Mix_ExpireChannel, 4.3.11 Mix_FadeOutChannel, 4.3.12 Mix_ChannelFinished

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_ExpireChannel

4.3.10 Mix_ExpireChannel

int Mix_ExpireChannel(int channel, int ticks)

channel
Channel to stop playing, or -1 for all channels.
ticks
Millisecons until channel(s) halt playback.

Halt channel playback, or all channels if -1 is passed in, after ticks milliseconds. Any callback set by Mix_ChannelFinished will be called when the channel expires.

Returns: Number of channels set to expire. Whether or not they are active.

// halt playback on all channels in 2 seconds
Mix_ExpireChannel(-1, 2000);

See Also:
4.3.9 Mix_HaltChannel, 4.3.11 Mix_FadeOutChannel, 4.3.12 Mix_ChannelFinished

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_FadeOutChannel

4.3.11 Mix_FadeOutChannel

int Mix_FadeOutChannel(int channel, int ms)

channel
Channel to fade out, or -1 to fade all channels out.
ms
Milliseconds of time that the fade-out effect should take to go to silence, starting now.

Gradually fade out which channel over ms milliseconds starting from now. The channel will be halted after the fade out is completed. Only channels that are playing are set to fade out, including paused channels. Any callback set by Mix_ChannelFinished will be called when the channel finishes fading out.

Returns: The number of channels set to fade out.

// fade out all channels to finish 3 seconds from now
printf("starting fade out of %d channels\n", Mix_FadeOutChannel(-1, 3000));

See Also:
4.3.5 Mix_FadeInChannel, 4.3.6 Mix_FadeInChannelTimed, 4.3.15 Mix_FadingChannel, 4.3.12 Mix_ChannelFinished

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_ChannelFinished

4.3.12 Mix_ChannelFinished

void Mix_ChannelFinished(void (*channel_finished)(int channel))

channel_finished
Function to call when any channel finishes playback.

When channel playback is halted, then the specified channel_finished function is called. The channel parameter will contain the channel number that has finished.
NOTE: NEVER call SDL_Mixer functions, nor SDL_LockAudio, from a callback function.

// a simple channel_finished function
void channelDone(int channel) {
    printf("channel %d finished playback.\n",channel);
}

// make a channelDone function
void channelDone(int channel)
{
    printf("channel %d finished playing.\n", channel);
}
...
// set the callback for when a channel stops playing
Mix_ChannelFinished(channelDone);

See Also:
4.3.9 Mix_HaltChannel, 4.3.10 Mix_ExpireChannel

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_Playing

4.3.13 Mix_Playing

int Mix_Playing(int channel)

channel
Channel to test whether it is playing or not.
-1 will tell you how many channels are playing.

Tells you if channel is playing, or not.
Note: Does not check if the channel has been paused.

Returns: Zero if the channel is not playing. Otherwise if you passed in -1, the number of channels playing is returned. If you passed in a specific channel, then 1 is returned if it is playing.

// check how many channels are playing samples
printf("%d channels are playing\n", Mix_Playing(-1));

See Also:
4.3.14 Mix_Paused, 5.4 Mix_Fading, 4.3.3 Mix_PlayChannel, 4.3.7 Mix_Pause,

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_Paused

4.3.14 Mix_Paused

int Mix_Paused(int channel)

channel
Channel to test whether it is paused or not.
-1 will tell you how many channels are paused.

Tells you if channel is paused, or not.
Note: Does not check if the channel has been halted after it was paused, which may seem a little weird.

Returns: Zero if the channel is not paused. Otherwise if you passed in -1, the number of paused channels is returned. If you passed in a specific channel, then 1 is returned if it is paused.

// check the pause status on all channels
printf("%d channels are paused\n", Mix_Paused(-1));

See Also:
4.3.13 Mix_Playing, 4.3.7 Mix_Pause, 4.3.8 Mix_Resume

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_FadingChannel

4.3.15 Mix_FadingChannel

Mix_Fading Mix_FadingChannel(int which)

which
Channel to get the fade activity status from.
-1 is not valid, and will probably crash the program.

Tells you if which channel is fading in, out, or not. Does not tell you if the channel is playing anything, or paused, so you'd need to test that separately.

Returns: the fading status. Never returns an error.

// check the fade status on channel 0
switch(Mix_FadingChannel(0)) {
    case MIX_NO_FADING:
        printf("Not fading.\n");
        break;
    case MIX_FADING_OUT:
        printf("Fading out.\n");
        break;
    case MIX_FADING_IN:
        printf("Fading in.\n");
        break;
}

See Also:
5.4 Mix_Fading, 4.3.13 Mix_Playing, 4.3.14 Mix_Paused, 4.3.5 Mix_FadeInChannel, 4.3.6 Mix_FadeInChannelTimed, 4.3.11 Mix_FadeOutChannel

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_GetChunk

4.3.16 Mix_GetChunk

Mix_Chunk *Mix_GetChunk(int channel)

channel
Channel to get the current Mix_Chunk playing.
-1 is not valid, but will not crash the program.

Get the most recent sample chunk pointer played on channel. This pointer may be currently playing, or just the last used.
Note: The actual chunk may have been freed, so this pointer may not be valid anymore.

Returns: Pointer to the Mix_Chunk. NULL is returned if the channel is not allocated, or if the channel has not played any samples yet.

// get the last chunk used by channel 0
printf("Mix_Chunk* last in use on channel 0 was: %08p\n", Mix_GetChunk(0));

See Also:
5.1 Mix_Chunk, 4.3.13 Mix_Playing

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Groups

4.4 Groups

These functions work with groupings of mixer channels.

The default group tag number of -1, which refers to ALL channels.

Setup
4.4.1 Mix_ReserveChannels Prevent channels from being used in default group
TODO
4.4.2 Mix_GroupChannel | Add/remove channel to/from group
4.4.3 Mix_GroupChannels | Add/remove segment of channels to/from group
Info
4.4.4 Mix_GroupCount | Get number of channels in group
4.4.5 Mix_GroupAvailable | Get first inactive channel in group
4.4.6 Mix_GroupOldest | Get oldest busy channel in group
4.4.7 Mix_GroupNewer | Get youngest busy channel in group
Stopping
4.4.8 Mix_FadeOutGroup | Fade out a group over time
4.4.9 Mix_HaltGroup | Stop a group

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_ReserveChannels

4.4.1 Mix_ReserveChannels

int Mix_ReserveChannels(int num)

num
Number of channels to reserve from default mixing.
Zero removes all reservations.

Reserve num channels from being used when playing samples when passing in -1 as a channel number to playback functions. The channels are reserved starting from channel 0 to num-1. Passing in zero will unreserve all channels. Normally SDL_mixer starts without any channels reserved.

The following functions are affected by this setting:
4.3.3 Mix_PlayChannel
4.3.4 Mix_PlayChannelTimed
4.3.5 Mix_FadeInChannel
4.3.6 Mix_FadeInChannelTimed

Returns: The number of channels reserved. Never fails, but may return less channels than you ask for, depending on the number of channels previously allocated.

// reserve the first 8 mixing channels
int reserved_count;
reserved_count=Mix_ReserveChannels(8);
if(reserved_count!=8) {
    printf("reserved %d channels from default mixing.\n",reserved_count);
    printf("8 channels were not reserved!\n");
    // this might be a critical error...
}

See Also:
4.3.1 Mix_AllocateChannels

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_GroupChannel

4.4.2 Mix_GroupChannel

int Mix_GroupChannel(int which, int tag)

which
Channel number of channels to assign tag to.
tag
A group number Any positive numbers (including zero).
-1 is the default group. Use -1 to remove a group tag essentially.

Add which channel to group tag, or reset it's group to the default group tag (-1).

Returns: True(1) on success. False(0) is returned when the channel specified is invalid.

// add channel 0 to group 1
if(!Mix_GroupChannel(0,1)) {
    // bad channel, apparently channel 1 isn't allocated
}

See Also:
4.4.3 Mix_GroupChannels, 4.3.1 Mix_AllocateChannels

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_GroupChannels

4.4.3 Mix_GroupChannels

int Mix_GroupChannels(int from, int to, int tag)

from
First Channel number of channels to assign tag to. Must be less or equal to to.
to
Last Channel number of channels to assign tag to. Must be greater or equal to from.
tag
A group number. Any positive numbers (including zero).
-1 is the default group. Use -1 to remove a group tag essentially.

Add channels starting at from up through to to group tag, or reset it's group to the default group tag (-1).

Returns: The number of tagged channels on success. If that number is less than to-from+1 then some channels were no tagged because they didn't exist.

// add channels 0 through 7 to group 1
if(Mix_GroupChannels(0,7,1)!=8) {
    // some bad channels, apparently some channels aren't allocated
}

See Also:
4.4.2 Mix_GroupChannel, 4.3.1 Mix_AllocateChannels

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_GroupCount

4.4.4 Mix_GroupCount

int Mix_GroupCount(int tag)

tag
A group number Any positive numbers (including zero).
-1 will count ALL channels.

Count the number of channels in group tag.

Returns: The number of channels found in the group. This function never fails.

// count the number of channels in group 1
printf("There are %d channels in group 1\n", Mix_GroupCount(1));

See Also:
4.4.2 Mix_GroupChannel, 4.4.3 Mix_GroupChannels

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_GroupAvailable

4.4.5 Mix_GroupAvailable

int Mix_GroupAvailable(int tag)

tag
A group number Any positive numbers (including zero).
-1 will search ALL channels.

Find the first available (not playing) channel in group tag.

Returns: The channel found on success. -1 is returned when no channels in the group are available.

// find the first available channel in group 1
int channel;
channel=Mix_GroupAvailable(1);
if (channel==-1) {
    // no channel available...
    // perhaps search for oldest or newest channel in use...
}

See Also:
4.4.6 Mix_GroupOldest, 4.4.7 Mix_GroupNewer, 4.4.2 Mix_GroupChannel, 4.4.3 Mix_GroupChannels

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_GroupOldest

4.4.6 Mix_GroupOldest

int Mix_GroupOldest(int tag)

tag
A group number Any positive numbers (including zero).
-1 will search ALL channels.

Find the oldest actively playing channel in group tag.

Returns: The channel found on success. -1 is returned when no channels in the group are playing or the group is empty.

// find the oldest playing channel in group 1
int channel;
channel=Mix_GroupOldest(1);
if (channel==-1) {
    // no channel playing or allocated...
    // perhaps just search for an available channel...
}

See Also:
4.4.7 Mix_GroupNewer, 4.4.5 Mix_GroupAvailable, 4.4.2 Mix_GroupChannel, 4.4.3 Mix_GroupChannels

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_GroupNewer

4.4.7 Mix_GroupNewer

int Mix_GroupNewer(int tag)

tag
A group number Any positive numbers (including zero).
-1 will search ALL channels.

Find the newest, most recently started, actively playing channel in group tag.

Returns: The channel found on success. -1 is returned when no channels in the group are playing or the group is empty.

// find the newest playing channel in group 1
int channel;
channel=Mix_GroupNewer(1);
if (channel==-1) {
    // no channel playing or allocated...
    // perhaps just search for an available channel...
}

See Also:
4.4.6 Mix_GroupOldest, 4.4.5 Mix_GroupAvailable, 4.4.2 Mix_GroupChannel, 4.4.3 Mix_GroupChannels

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_FadeOutGroup

4.4.8 Mix_FadeOutGroup

int Mix_FadeOutGroup(int tag, int ms)

tag
Group to fade out.
NOTE: -1 will NOT fade all channels out. Use Mix_FadeOutChannel(-1) for that instead.
ms
Milliseconds of time that the fade-out effect should take to go to silence, starting now.

Gradually fade out channels in group tag over ms milliseconds starting from now. The channels will be halted after the fade out is completed. Only channels that are playing are set to fade out, including paused channels. Any callback set by Mix_ChannelFinished will be called when each channel finishes fading out.

Returns: The number of channels set to fade out.

// fade out all channels in group 1 to finish 3 seconds from now
printf("starting fade out of %d channels\n", Mix_FadeOutGroup(1, 3000));

See Also:
4.4.9 Mix_HaltGroup, 4.3.11 Mix_FadeOutChannel, 4.3.15 Mix_FadingChannel, 4.3.12 Mix_ChannelFinished

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_HaltGroup

4.4.9 Mix_HaltGroup

int Mix_HaltGroup(int tag)

tag
Group to fade out.
NOTE: -1 will NOT halt all channels. Use Mix_HaltChannel(-1) for that instead.

Halt playback on all channels in group tag.
Any callback set by Mix_ChannelFinished will be called once for each channel that stops.

Returns: always returns zero. (more silly than Mix_HaltChannel)

// halt playback on all channels in group 1
Mix_HaltGroup(1);

See Also:
4.4.8 Mix_FadeOutGroup, 4.3.9 Mix_HaltChannel, 4.3.12 Mix_ChannelFinished

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Music

4.5 Music

These functions work with music. Music is not played on a normal mixer channel. Music is therefore manipulated separately, except in post-processing hooks.

Loading
4.5.1 Mix_GetNumMusicDecoders | Number of music format types that can be decoded
4.5.2 Mix_GetMusicDecoder | Name of enumerated music format type decoder
4.5.3 Mix_LoadMUS | Load a music file into a Mix_Music
Free
4.5.4 Mix_FreeMusic Free a Mix_Music
Playing
4.5.5 Mix_PlayMusic | Play music, with looping
4.5.6 Mix_FadeInMusic | Play music, with looping, and fade in
4.5.7 Mix_FadeInMusicPos | Play music from a start point, with looping, and fade in
4.5.8 Mix_HookMusic | Hook for a custom music player
Settings
4.5.9 Mix_VolumeMusic | Set music volume
4.5.10 Mix_PauseMusic | Pause music
4.5.11 Mix_ResumeMusic | Resume paused music
4.5.12 Mix_RewindMusic | Rewind music to beginning
4.5.13 Mix_SetMusicPosition | Set position of playback in stream
4.5.14 Mix_SetMusicCMD | Use external program for music playback
Stopping
4.5.15 Mix_HaltMusic | Stop music playback
4.5.16 Mix_FadeOutMusic | Stop music, with fade out
4.5.17 Mix_HookMusicFinished | Set a callback for when music stops
Info
4.5.18 Mix_GetMusicType | Get the music encoding type
4.5.19 Mix_PlayingMusic | Test whether music is playing
4.5.20 Mix_PausedMusic | Test whether music is paused
4.5.21 Mix_FadingMusic | Get status of current music fade activity
4.5.22 Mix_GetMusicHookData | Retrieve the Mix_HookMusic arg

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_GetNumMusicDecoders

4.5.1 Mix_GetNumMusicDecoders

int Mix_GetNumMusicDecoders()

Get the number of music decoders available from the Mix_GetMusicDecoder function. This number can be different for each run of a program, due to the change in availability of shared libraries that support each format.

Returns: The number of music decoders available.

// print the number of music decoders available
printf("There are %d music deocoders available\n", Mix_GetNumMusicDecoders());

See Also:
4.2.1 Mix_GetNumChunkDecoders, 4.5.2 Mix_GetMusicDecoder, 4.5.3 Mix_LoadMUS

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_GetMusicDecoder

4.5.2 Mix_GetMusicDecoder

const char *Mix_GetMusicDecoder(int index)

index
The index number of music decoder to get.
In the range from 0(zero) to Mix_GetNumMusicDecoders()-1, inclusive.

Get the name of the indexed music decoder. You need to get the number of music decoders available using the Mix_GetNumMusicDecoders function.

Returns: The name of the indexed music decoder. This string is owned by the SDL_mixer library, do not modify or free it. It is valid until you call Mix_CloseAudio the final time.

// print music decoders available
int i,max=Mix_GetNumMusicDecoders();
for(i=0; i<max; ++i)
    printf("Music decoder %d is for %s",Mix_GetMusicDecoder(i));

See Also:
4.5.1 Mix_GetNumMusicDecoders, 4.2.2 Mix_GetChunkDecoder, 4.2.3 Mix_LoadWAV

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_LoadMUS

4.5.3 Mix_LoadMUS

Mix_Music *Mix_LoadMUS(const char *file)

file
Name of music file to use.

Load music file to use. This can load WAVE, MOD, MIDI, OGG, MP3, FLAC, and any file that you use a command to play with.
If you are using an external command to play the music, you must call Mix_SetMusicCMD before this, otherwise the internal players will be used. Alternatively, if you have set an external command up and don't want to use it, you must call Mix_SetMusicCMD(NULL) to use the built-in players again.

Returns: A pointer to a Mix_Music. NULL is returned on errors.

// load the MP3 file "music.mp3" to play as music
Mix_Music *music;
music=Mix_LoadMUS("music.mp3");
if(!music) {
    printf("Mix_LoadMUS(\"music.mp3\"): %s\n", Mix_GetError());
    // this might be a critical error...
}

See Also:
5.2 Mix_Music, 4.5.14 Mix_SetMusicCMD, 4.5.5 Mix_PlayMusic, 4.5.6 Mix_FadeInMusic, 4.5.7 Mix_FadeInMusicPos

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_FreeMusic

4.5.4 Mix_FreeMusic

void Mix_FreeMusic(Mix_Music *music)

music
Pointer to Mix_Music to free.

Free the loaded music. If music is playing it will be halted. If music is fading out, then this function will wait (blocking) until the fade out is complete.

// free music
Mix_Music *music;
Mix_FreeMusic(music);
music=NULL; // so we know we freed it...

See Also:
4.5.3 Mix_LoadMUS

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_PlayMusic

4.5.5 Mix_PlayMusic

int Mix_PlayMusic(Mix_Music *music, int loops)

music
Pointer to Mix_Music to play.
loops
number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)

Play the loaded music loop times through from start to finish. The previous music will be halted, or if fading out it waits (blocking) for that to finish.

Returns: 0 on success, or -1 on errors.

// play music forever
// Mix_Music *music; // I assume this has been loaded already
if(Mix_PlayMusic(music, -1)==-1) {
    printf("Mix_PlayMusic: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
4.5.6 Mix_FadeInMusic

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_FadeInMusic

4.5.6 Mix_FadeInMusic

int Mix_FadeInMusic(Mix_Music *music, int loops, int ms)

music
Pointer to Mix_Music to play.
loops
number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)
ms
Milliseconds for the fade-in effect to complete.

Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish.
The fade in effect only applies to the first loop.
Any previous music will be halted, or if it is fading out it will wait (blocking) for the fade to complete.
This function is the same as Mix_FadeInMusicPos(music, loops, ms, 0).

Returns: 0 on success, or -1 on errors.

// play music forever, fading in over 2 seconds
// Mix_Music *music; // I assume this has been loaded already
if(Mix_FadeInMusic(music, -1, 2000)==-1) {
    printf("Mix_FadeInMusic: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
4.5.5 Mix_PlayMusic, 4.5.7 Mix_FadeInMusicPos

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_FadeInMusicPos

4.5.7 Mix_FadeInMusicPos

int Mix_FadeInMusicPos(Mix_Music *music, int loops, int ms, double position)

music
Pointer to Mix_Music to play.
loops
number of times to play through the music.
0 plays the music zero times...
-1 plays the music forever (or as close as it can get to that)
ms
Milliseconds for the fade-in effect to complete.
position
Posistion to play from, see Mix_SetMusicPosition for meaning.

Fade in over ms milliseconds of time, the loaded music, playing it loop times through from start to finish.
The fade in effect only applies to the first loop.
The first time the music is played, it posistion will be set to posistion, which means different things for different types of music files, see Mix_SetMusicPosition for more info on that.
Any previous music will be halted, or if it is fading out it will wait (blocking) for the fade to complete.

Returns: 0 on success, or -1 on errors.

// play music forever, fading in over 2 seconds
// Mix_Music *music; // I assume this has been loaded already
if(Mix_FadeInMusicPos(music, -1, 2000)==-1) {
    printf("Mix_FadeInMusic: %s\n", Mix_GetError());
    // well, there's no music, but most games don't break without music...
}

See Also:
4.5.5 Mix_PlayMusic, 4.5.6 Mix_FadeInMusic, 4.5.13 Mix_SetMusicPosition

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_HookMusic

4.5.8 Mix_HookMusic

void Mix_HookMusic(void (*mix_func)(void *udata, Uint8 *stream, int len),
                   void *arg)

mix_func
Function pointer to a music player mixer function.
NULL will stop the use of the music player, returning the mixer to using the internal music players like usual.
arg
This is passed to the mix_func's udata parameter when it is called.

This sets up a custom music player function. The function will be called with arg passed into the udata parameter when the mix_func is called. The stream parameter passes in the audio stream buffer to be filled with len bytes of music. The music player will then be called automatically when the mixer needs it. Music playing will start as soon as this is called. All the music playing and stopping functions have no effect on music after this. Pause and resume will work. Using a custom music player and the internal music player is not possible, the custom music player takes priority. To stop the custom music player call Mix_HookMusic(NULL, NULL).
NOTE: NEVER call SDL_Mixer functions, nor SDL_LockAudio, from a callback function.

// make a music play function
// it expects udata to be a pointer to an int
void myMusicPlayer(void *udata, Uint8 *stream, int len)
{
    int i, pos=*(int*)udata;

    // fill buffer with...uh...music...
    for(i=0; i<len; i++)
        stream[i]=(i+pos)&ff;

    // set udata for next time
    pos+=len;
    *(int*)udata=pos;
}
...
// use myMusicPlayer for playing...uh...music
int music_pos=0;
Mix_HookMusic(myMusicPlayer, &music_pos);

See Also:
4.5.14 Mix_SetMusicCMD, 4.5.22 Mix_GetMusicHookData

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_VolumeMusic

4.5.9 Mix_VolumeMusic

int Mix_VolumeMusic(int volume)

volume
Music volume, from 0 to MIX_MAX_VOLUME(128).
Values greater than MIX_MAX_VOLUME will use MIX_MAX_VOLUME.
-1 does not set the volume, but does return the current volume setting.

Set the volume to volume, if it is 0 or greater, and return the previous volume setting. Setting the volume during a fade will not work, the faders use this function to perform their effect! Setting volume while using an external music player set by Mix_SetMusicCMD will have no effect, and Mix_GetError will show the reason why not.

Returns: The previous volume setting.

// set the music volume to 1/2 maximum, and then check it
printf("volume was    : %d\n", Mix_VolumeMusic(MIX_MAX_VOLUME/2));
printf("volume is now : %d\n", Mix_VolumeMusic(-1));

See Also:
4.5.6 Mix_FadeInMusic, 4.5.16 Mix_FadeOutMusic, 4.5.14 Mix_SetMusicCMD

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_PauseMusic

4.5.10 Mix_PauseMusic

void Mix_PauseMusic()

Pause the music playback. You may halt paused music.
Note: Music can only be paused if it is actively playing.

// pause music playback
Mix_PauseMusic();

See Also:
4.5.11 Mix_ResumeMusic, 4.5.20 Mix_PausedMusic, 4.5.15 Mix_HaltMusic

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_ResumeMusic

4.5.11 Mix_ResumeMusic

void Mix_ResumeMusic()

Unpause the music. This is safe to use on halted, paused, and already playing music.

// resume music playback
Mix_ResumeMusic();

See Also:
4.5.10 Mix_PauseMusic, 4.5.20 Mix_PausedMusic

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_RewindMusic

4.5.12 Mix_RewindMusic

void Mix_RewindMusic()

Rewind the music to the start. This is safe to use on halted, paused, and already playing music. It is not useful to rewind the music immediately after starting playback, because it starts at the beginning by default.

This function only works for these streams: MOD, OGG, MP3, Native MIDI.

// rewind music playback to the start
Mix_RewindMusic();

See Also:
4.5.5 Mix_PlayMusic

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_SetMusicPosition

4.5.13 Mix_SetMusicPosition

int Mix_SetMusicPosition(double position)

position
Posistion to play from.

Set the position of the currently playing music. The position takes different meanings for different music sources. It only works on the music sources listed below.

MOD
The double is cast to Uint16 and used for a pattern number in the module.
Passing zero is similar to rewinding the song.
OGG
Jumps to position seconds from the beginning of the song.
MP3
Jumps to position seconds from the current position in the stream.
So you may want to call Mix_RewindMusic before this.
Does not go in reverse...negative values do nothing.

Returns: 0 on success, or -1 if the codec doesn't support this function.

// skip one minute into the song, from the start
// this assumes you are playing an MP3
Mix_RewindMusic();
if(Mix_SetMusicPosition(60.0)==-1) {
    printf("Mix_SetMusicPosition: %s\n", Mix_GetError());
}

See Also:
4.5.7 Mix_FadeInMusicPos

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_SetMusicCMD

4.5.14 Mix_SetMusicCMD

int Mix_SetMusicCMD(const char *command)

command
System command to play the music. Should be a complete command, as if typed in to the command line, but it should expect the filename to be added as the last argument.
NULL will turn off using an external command for music, returning to the internal music playing functionality.

Setup a command line music player to use to play music. Any music playing will be halted. The music file to play is set by calling Mix_LoadMUS(filename), and the filename is appended as the last argument on the commandline. This allows you to reuse the music command to play multiple files. The command will be sent signals SIGTERM to halt, SIGSTOP to pause, and SIGCONT to resume. The command program should react correctly to those signals for it to function properly with SDL_Mixer. Mix_VolumeMusic has no effect when using an external music player, and Mix_GetError will have an error code set. You should set the music volume in the music player's command if the music player supports that. Looping music works, by calling the command again when the previous music player process has ended. Playing music through a command uses a forked process to execute the music command.
To use the internal music players set the command to NULL.
NOTE: External music is not mixed by SDL_mixer, so no post-processing hooks will be for music.
NOTE: Playing music through an external command may not work if the sound driver does not support multiple openings of the audio device, since SDL_Mixer already has the audio device open for playing samples through channels.
NOTE: Commands are not totally portable, so be careful.

Returns: 0 on success, or -1 on any errors, such as running out of memory.

// use mpg123 to play music
Mix_Music *music=NULL;
if(Mix_SetMusicCMD("mpg123 -q")==-1) {
    perror("Mix_SetMusicCMD");
} else {
    // play some mp3 file
    music=Mix_LoadMUS("music.mp3");
    if(music) {
        Mix_PlayMusic(music,1);
    }
}

See Also:
4.5.5 Mix_PlayMusic, 4.5.9 Mix_VolumeMusic

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_HaltMusic

4.5.15 Mix_HaltMusic

int Mix_HaltMusic()

Halt playback of music. This interrupts music fader effects. Any callback set by Mix_HookMusicFinished will be called when the music stops.

Returns: always returns zero. (even more silly than Mix_HaltGroup)

// halt music playback
Mix_HaltMusic();

See Also:
4.5.16 Mix_FadeOutMusic, 4.5.17 Mix_HookMusicFinished

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_FadeOutMusic

4.5.16 Mix_FadeOutMusic

int Mix_FadeOutMusic(int ms)

ms
Milliseconds of time that the fade-out effect should take to go to silence, starting now.

Gradually fade out the music over ms milliseconds starting from now. The music will be halted after the fade out is completed. Only when music is playing and not fading already are set to fade out, including paused channels. Any callback set by Mix_HookMusicFinished will be called when the music finishes fading out.

Returns: 1 on success, 0 on failure.

// fade out music to finish 3 seconds from now
while(!Mix_FadeOutMusic(3000) && Mix_PlayingMusic()) {
    // wait for any fades to complete
    SDL_Delay(100);
}

See Also:
4.5.15 Mix_HaltMusic, 4.5.21 Mix_FadingMusic, 4.5.19 Mix_PlayingMusic, 4.5.17 Mix_HookMusicFinished

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_HookMusicFinished

4.5.17 Mix_HookMusicFinished

void Mix_HookMusicFinished(void (*music_finished)())

music_finished
Function pointer to a void function().
NULL will remove the hook.

This sets up a function to be called when music playback is halted. Any time music stops, the music_finished function will be called. Call with NULL to remove the callback.
NOTE: NEVER call SDL_Mixer functions, nor SDL_LockAudio, from a callback function.

// make a music finished function
void musicFinished()
{
    printf("Music stopped.\n");
}
...
// use musicFinished for when music stops
Mix_HookMusicFinished(musicFinished);

See Also:
4.5.15 Mix_HaltMusic, 4.5.16 Mix_FadeOutMusic

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_GetMusicType

4.5.18 Mix_GetMusicType

Mix_MusicType Mix_GetMusicType(const Mix_Music *music)

music
The music to get the type of.
NULL will get the currently playing music type.

Tells you the file format encoding of the music. This may be handy when used with Mix_SetMusicPosition, and other music functions that vary based on the type of music being played. If you want to know the type of music currently being played, pass in NULL to music.

Returns: The type of music or if music is NULL then the currently playing music type, otherwise MUS_NONE if no music is playing.

// print the type of music currently playing
switch(Mix_GetMusicType(NULL))
{
    case MUS_NONE:
    MUS_CMD:
        printf("Command based music is playing.\n");
        break;
    MUS_WAV:
        printf("WAVE/RIFF music is playing.\n");
        break;
    MUS_MOD:
        printf("MOD music is playing.\n");
        break;
    MUS_MID:
        printf("MIDI music is playing.\n");
        break;
    MUS_OGG:
        printf("OGG music is playing.\n");
        break;
    MUS_MP3:
        printf("MP3 music is playing.\n");
        break;
    default:
        printf("Unknown music is playing.\n");
        break;
}

See Also:
5.3 Mix_MusicType, 4.6.7 Mix_SetPosition

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_PlayingMusic

4.5.19 Mix_PlayingMusic

int Mix_PlayingMusic()

Tells you if music is actively playing, or not.
Note: Does not check if the channel has been paused.

Returns: Zero if the music is not playing, or 1 if it is playing.

// check if music is playing
printf("music is%s playing.\n", Mix_PlayingMusic()?"":" not");

See Also:
4.5.20 Mix_PausedMusic, 4.5.21 Mix_FadingMusic, 4.5.5 Mix_PlayMusic

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_PausedMusic

4.5.20 Mix_PausedMusic

int Mix_PausedMusic()

Tells you if music is paused, or not.
Note: Does not check if the music was been halted after it was paused, which may seem a little weird.

Returns: Zero if music is not paused. 1 if it is paused.

// check the music pause status
printf("music is%s paused\n", Mix_PausedMusic()?"":" not");

See Also:
4.5.19 Mix_PlayingMusic, 4.5.10 Mix_PauseMusic, 4.5.11 Mix_ResumeMusic

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_FadingMusic

4.5.21 Mix_FadingMusic

Mix_Fading Mix_FadingMusic()

Tells you if music is fading in, out, or not at all. Does not tell you if the channel is playing anything, or paused, so you'd need to test that separately.

Returns: the fading status. Never returns an error.

// check the music fade status
switch(Mix_FadingMusic()) {
    case MIX_NO_FADING:
        printf("Not fading music.\n");
        break;
    case MIX_FADING_OUT:
        printf("Fading out music.\n");
        break;
    case MIX_FADING_IN:
        printf("Fading in music.\n");
        break;
}

See Also:
5.4 Mix_Fading, 4.5.20 Mix_PausedMusic, 4.5.19 Mix_PlayingMusic, 4.5.7 Mix_FadeInMusicPos, 4.5.16 Mix_FadeOutMusic

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_GetMusicHookData

4.5.22 Mix_GetMusicHookData

void *Mix_GetMusicHookData()

Get the arg passed into Mix_HookMusic.

Returns: the arg pointer.

// retrieve the music hook data pointer
void *data;
data=Mix_GetMusicHookData();

See Also:
4.5.8 Mix_HookMusic

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Effects

4.6 Effects

These functions are for special effects processing. Not all effects are all that special. All effects are post processing routines that are either built-in to SDL_mixer or created by you. Effects can be applied to individual channels, or to the final mixed stream which contains all the channels including music.

Registration
4.6.1 Mix_RegisterEffect | Hook a processor to a channel
4.6.2 Mix_UnregisterEffect | Unhook a processor from a channel
4.6.3 Mix_UnregisterAllEffects | Unhook all processors from a channel
4.6.4 Mix_SetPostMix | Hook in a postmix processor
Built-in Processors
4.6.5 Mix_SetPanning | Stereo panning
4.6.6 Mix_SetDistance | Distance attenuation (volume)
4.6.7 Mix_SetPosition | Panning(angular) and distance
4.6.8 Mix_SetReverseStereo | Swap stereo left and right

The built-in processors: Mix_SetPanning, Mix_SetPosition, Mix_SetDistance, and
Mix_SetReverseStereo, all look for an environment variable, MIX_EFFECTSMAXSPEED to be defined. If the environment variable is defined these processors may use more memory or reduce the quality of the effects, all for better speed.

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_RegisterEffect

4.6.1 Mix_RegisterEffect

int Mix_RegisterEffect(int chan, Mix_EffectFunc_t f, Mix_EffectDone_t d,
                       void *arg)

chan
channel number to register f and d on.
Use MIX_CHANNEL_POST to process the postmix stream.
f
The function pointer for the effects processor.
d
The function pointer for any cleanup routine to be called when the channel is done playing a sample.
This may be NULL for any processors that don't need to clean up any memory or other dynamic data.
arg
A pointer to data to pass into the f's and d's udata parameter. It is a good place to keep the state data for the processor, especially if the processor is made to handle multiple channels at the same time.
This may be NULL, depending on the processor.

Hook a processor function f into a channel for post processing effects. You may just be reading the data and displaying it, or you may be altering the stream to add an echo. Most processors also have state data that they allocate as they are in use, this would be stored in the arg pointer data space. When a processor is finished being used, any function passed into d will be called, which is when your processor should clean up the data in the arg data space.
The effects are put into a linked list, and always appended to the end, meaning they always work on previously registered effects output. Effects may be added multiple times in a row. Effects are cumulative this way.

Returns: Zero on errors, such as a nonexisting channel.

// make a passthru processor function that does nothing...
void noEffect(int chan, void *stream, int len, void *udata)
{
    // you could work with stream here...
}
...
// register noEffect as a postmix processor
if(!Mix_RegisterEffect(MIX_CHANNEL_POST, noEffect, NULL, NULL)) {
    printf("Mix_RegisterEffect: %s\n", Mix_GetError());
}

See Also:
4.6.2 Mix_UnregisterEffect, 4.6.3 Mix_UnregisterAllEffects

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_UnregisterEffect

4.6.2 Mix_UnregisterEffect

int Mix_UnregisterEffect(int channel, Mix_EffectFunc_t f)

channel
Channel number to remove f from as a post processor.
Use MIX_CHANNEL_POST for the postmix stream.
f
The function to remove from channel.

Remove the oldest (first found) registered effect function f from the effect list for channel. This only removes the first found occurance of that function, so it may need to be called multiple times if you added the same function multiple times, just stop removing when Mix_UnregisterEffect returns an error, to remove all occurances of f from a channel.
If the channel is active the registered effect will have its Mix_EffectDone_t function called, if it was specified in Mix_RegisterEffect.

Returns: Zero on errors, such as invalid channel, or effect function not registered on channel.

// unregister the noEffect from the postmix effects
// this removes all occurances of noEffect registered to the postmix
while(Mix_UnregisterEffect(MIX_CHANNEL_POST, noEffect));
// you may print Mix_GetError() if you want to check it.
// it should say "No such effect registered" after this loop.

See Also:
4.6.3 Mix_UnregisterAllEffects, 4.6.1 Mix_RegisterEffect

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_UnregisterAllEffects

4.6.3 Mix_UnregisterAllEffects

int Mix_UnregisterAllEffects(int channel)

channel
Channel to remove all effects from.
Use MIX_CHANNEL_POST for the postmix stream.

This removes all effects registered to channel. If the channel is active all the registered effects will have their Mix_EffectDone_t functions called, if they were specified in Mix_RegisterEffect.

Returns: Zero on errors, such as channel not existing.

// remove all effects from channel 0
if(!Mix_UnregisterAllEffects(0)) {
    printf("Mix_UnregisterAllEffects: %s\n", Mix_GetError());
}

See Also:
4.6.2 Mix_UnregisterEffect, 4.6.1 Mix_RegisterEffect

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_SetPostMix

4.6.4 Mix_SetPostMix

void Mix_SetPostMix(void (*mix_func)(void *udata, Uint8 *stream, int len),
                    void *arg)

mix_func
The function pointer for the postmix processor.
NULL unregisters the current postmixer.
arg
A pointer to data to pass into the mix_func's udata parameter. It is a good place to keep the state data for the processor, especially if the processor is made to handle multiple channels at the same time.
This may be NULL, depending on the processor.

Hook a processor function mix_func to the postmix stream for post processing effects. You may just be reading the data and displaying it, or you may be altering the stream to add an echo. Most processors also have state data that they allocate as they are in use, this would be stored in the arg pointer data space. This processor is never really finished, until the audio device is closed, or you pass NULL as the mix_func.
There can only be one postmix function used at a time through this method. Use Mix_RegisterEffect(MIX_CHANNEL_POST, mix_func, NULL, arg) to use multiple postmix processors.
This postmix processor is run AFTER all the registered postmixers set up by Mix_RegisterEffect.

// make a passthru processor function that does nothing...
void noEffect(void *udata, Uint8 *stream, int len)
{
    // you could work with stream here...
}
...
// register noEffect as a postmix processor
Mix_SetPostMix(noEffect, NULL);

See Also:
4.6.1 Mix_RegisterEffect

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_SetPanning

4.6.5 Mix_SetPanning

int Mix_SetPanning(int channel, Uint8 left, Uint8 right)

channel
Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream.
left
Volume for the left channel, range is 0(silence) to 255(loud)
right
Volume for the left channel, range is 0(silence) to 255(loud)

This effect will only work on stereo audio. Meaning you called Mix_OpenAudio with 2 channels (MIX_DEFAULT_CHANNELS). The easiest way to do true panning is to call Mix_SetPanning(channel, left, 254 - left); so that the total volume is correct, if you consider the maximum volume to be 127 per channel for center, or 254 max for left, this works, but about halves the effective volume.
This Function registers the effect for you, so don't try to Mix_RegisterEffect it yourself.
NOTE: Setting both left and right to 255 will unregister the effect from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.
NOTE: Using this function on a mono audio device will not register the effect, nor will it return an error status.

Returns: Zero on errors, such as bad channel, or if Mix_RegisterEffect failed.

// pan channel 1 halfway to the left
if(!Mix_SetPanning(1, 255, 127)) {
    printf("Mix_SetPanning: %s\n", Mix_GetError());
    // no panning, is it ok?
}

See Also:
4.6.7 Mix_SetPosition, 4.6.3 Mix_UnregisterAllEffects

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_SetDistance

4.6.6 Mix_SetDistance

int Mix_SetDistance(int channel, Uint8 distance)

channel
Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream.
distance
Specify the distance from the listener, from 0(close/loud) to 255(far/quiet).

This effect simulates a simple attenuation of volume due to distance. The volume never quite reaches silence, even at max distance.
NOTE: Using a distance of 0 will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.

Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect failed.

// distance channel 1 to be farthest away
if(!Mix_SetDistance(1, 255)) {
    printf("Mix_SetDistance: %s\n", Mix_GetError());
    // no distance, is it ok?
}

See Also:
4.6.7 Mix_SetPosition, 4.6.3 Mix_UnregisterAllEffects

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_SetPosition

4.6.7 Mix_SetPosition

int Mix_SetPosition(int channel, Sint16 angle, Uint8 distance)

channel
Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream.
angle
Direction in relation to forward from 0 to 360 degrees. Larger angles will be reduced to this range using angles % 360.
0 = directly in front.
90 = directly to the right.
180 = directly behind.
270 = directly to the left.
So you can see it goes clockwise starting at directly in front.
This ends up being similar in effect to Mix_SetPanning.
distance
The distance from the listener, from 0(near/loud) to 255(far/quiet).
This is the same as the Mix_SetDistance effect.

This effect emulates a simple 3D audio effect. It's not all that realistic, but it can help improve some level of realism. By giving it the angle and distance from the camera's point of view, the effect pans and attenuates volumes. If you are looking for better positional audio, using OpenAL is suggested.
NOTE: Using angle and distance of 0, will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.

Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect failed.

// set channel 2 to be behind and right, and 100 units away
if(!Mix_SetPosition(2, 135, 100)) {
    printf("Mix_SetPosition: %s\n", Mix_GetError());
    // no position effect, is it ok?
}

See Also:
4.6.5 Mix_SetPanning, 4.6.6 Mix_SetDistance, 4.6.3 Mix_UnregisterAllEffects

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_SetReverseStereo

4.6.8 Mix_SetReverseStereo

int Mix_SetReverseStereo(int channel, int flip)

channel
Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream.
flip
Must be non-zero to work, means nothing to the effect processor itself.
set to zero to unregister the effect from channel.

Simple reverse stereo, swaps left and right channel sound.
NOTE: Using a flip of 0, will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.

Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect failed.

// set the total mixer output to be reverse stereo
if(!Mix_SetReverseStereo(MIX_CHANNEL_POST, 1)) {
    printf("Mix_SetReverseStereo: %s\n", Mix_GetError());
    // no reverse stereo, is it ok?
}

See Also:
4.6.3 Mix_UnregisterAllEffects

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Types

5. Types

These types are defined and used by the SDL_mixer API.

5.1 Mix_Chunk | The internal format for an audio chunk
5.2 Mix_Music | The internal format for a music chunk
5.3 Mix_MusicType | Music type enumerations
5.4 Mix_Fading | Fader effect type enumerations
5.5 Mix_EffectFunc_t | Special effect callback function pointer
5.6 Mix_EffectDone_t | Special effect done callback function pointer

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_Chunk

5.1 Mix_Chunk

typedef struct Mix_Chunk {
    int allocated;
    Uint8 *abuf;
    Uint32 alen;
    Uint8 volume;     /* Per-sample volume, 0-128 */
} Mix_Chunk;

allocated
a boolean indicating whether to free abuf when the chunk is freed.
0 if the memory was not allocated and thus not owned by this chunk.
1 if the memory was allocated and is thus owned by this chunk.
abuf
Pointer to the sample data, which is in the output format and sample rate.
alen
Length of abuf in bytes.
volume
0 = silent, 128 = max volume. This takes effect when mixing.

The internal format for an audio chunk. This stores the sample data, the length in bytes of that data, and the volume to use when mixing the sample.

See Also:
4.2.7 Mix_VolumeChunk, 4.3.16 Mix_GetChunk, 4.2.3 Mix_LoadWAV, 4.2.4 Mix_LoadWAV_RW, 4.2.8 Mix_FreeChunk, 5.2 Mix_Music

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_Music

5.2 Mix_Music

typedef struct _Mix_Music Mix_Music;

This is an opaque data type used for Music data. This should always be used as a pointer. Who knows why it isn't a pointer in this typedef...

See Also:
4.5.3 Mix_LoadMUS, 4.5.4 Mix_FreeMusic, 5.1 Mix_Chunk

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_MusicType

5.3 Mix_MusicType

typedef enum {
    MUS_NONE,
    MUS_CMD,
    MUS_WAV,
    MUS_MOD,
    MUS_MID,
    MUS_OGG,
    MUS_MP3, /* using SMPEG */
    MUS_MP3_MAD,
    MUS_FLAC
} Mix_MusicType;

Return values from Mix_GetMusicType are of these enumerated values.
If no music is playing then MUS_NONE is returned.
If music is playing via an external command then MUS_CMD is returned.
Otherwise they are self explanatory.

See Also:
4.5.18 Mix_GetMusicType

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_Fading

5.4 Mix_Fading

typedef enum {
    MIX_NO_FADING,
    MIX_FADING_OUT,
    MIX_FADING_IN
} Mix_Fading;

Return values from Mix_FadingMusic and Mix_FadingChannel are of these enumerated values. If no fading is taking place on the queried channel or music, then MIX_NO_FADING is returned. Otherwise they are self explanatory.

See Also:
4.3.15 Mix_FadingChannel, 4.5.21 Mix_FadingMusic

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_EffectFunc_t

5.5 Mix_EffectFunc_t

typedef void (*Mix_EffectFunc_t)(int chan, void *stream, int len,
                                 void *udata);

chan
The channel number that this effect is effecting now.
MIX_CHANNEL_POST is passed in for post processing effects over the final mix.
stream
The buffer containing the current sample to process.
len
The length of stream in bytes.
udata
User data pointer that was passed in to Mix_RegisterEffect when registering this effect processor function.

This is the prototype for effect processing functions. These functions are used to apply effects processing on a sample chunk. As a channel plays a sample, the registered effect functions are called. Each effect would then read and perhaps alter the len bytes of stream. It may also be advantageous to keep the effect state in the udata, with would be setup when registering the effect function on a channel.

See Also:
4.6.1 Mix_RegisterEffect 4.6.2 Mix_UnregisterEffect

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Mix_EffectDone_t

5.6 Mix_EffectDone_t

typedef void (*Mix_EffectDone_t)(int chan, void *udata);

chan
The channel number that this effect is effecting now.
MIX_CHANNEL_POST is passed in for post processing effects over the final mix.
udata
User data pointer that was passed in to Mix_RegisterEffect when registering this effect processor function.

This is the prototype for effect processing functions. This is called when a channel has finished playing, or halted, or is deallocated. This is also called when a processor is unregistered while processing is active. At that time the effects processing function may want to reset some internal variables or free some memory. It should free memory at least, because the processor could be freed after this call.

See Also:
4.6.1 Mix_RegisterEffect 4.6.2 Mix_UnregisterEffect

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Defines

6. Defines

SDL_MIXER_MAJOR_VERSION
1
SDL_mixer library major number at compilation time
SDL_MIXER_MINOR_VERSION
2
SDL_mixer library minor number at compilation time
SDL_MIXER_PATCHLEVEL
9
SDL_mixer library patch level at compilation time
MIX_CHANNELS
8
The default mixer has this many simultaneous mixing channels after the first call to Mix_OpenAudio.
MIX_DEFAULT_FREQUENCY
22050
Good default sample rate in Hz (samples per second) for PC sound cards.
MIX_DEFAULT_FORMAT
AUDIO_S16SYS
The suggested default is signed 16bit samples in host byte order.
MIX_DEFAULT_CHANNELS
2
Stereo sound is a good default.
MIX_MAX_VOLUME
128
Maximum value for any volume setting.
This is currently the same as SDL_MIX_MAXVOLUME.
MIX_CHANNEL_POST
-2
This is the channel number used for post processing effects.
MIX_EFFECTSMAXSPEED
"MIX_EFFECTSMAXSPEED"
A convience definition for the string name of the environment variable to define when you desire the internal effects to sacrifice quality and/or RAM for speed. The environment variable must be set (else nonexisting) before Mix_OpenAudio is called for the setting to take effect.

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Glossary

7. Glossary

Byte Order
Also known as Big-Endian. Which means the most significant byte comes first in storage. Sparc and Motorola 68k based chips are MSB ordered.
(SDL defines this as SDL_BYTEORDER==SDL_BIG_ENDIAN)

Little-Endian(LSB) is stored in the opposite order, with the least significant byte first in memory. Intel and AMD are two LSB machines.
(SDL defines this as SDL_BYTEORDER==SDL_LIL_ENDIAN)

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Index

Index

Jump to: B L M R S

 | Index Entry | Section
B |  |
 | Big-Endian | 7. Glossary
 | Byte Order | 7. Glossary
L |  |
 | Little-Endian | 7. Glossary
 | LSB | 7. Glossary
M |  |
 | Mix_AllocateChannels | 4.3.1 Mix_AllocateChannels
 | MIX_CHANNEL_POST | 6. Defines
 | Mix_ChannelFinished | 4.3.12 Mix_ChannelFinished
 | MIX_CHANNELS | 6. Defines
 | Mix_Chunk | 4.2 Samples
 | Mix_Chunk | 5.1 Mix_Chunk
 | Mix_CloseAudio | 4.1.5 Mix_CloseAudio
 | MIX_DEFAULT_CHANNELS | 6. Defines
 | MIX_DEFAULT_FORMAT | 6. Defines
 | MIX_DEFAULT_FREQUENCY | 6. Defines
 | Mix_EffectDone_t | 5.6 Mix_EffectDone_t
 | Mix_EffectFunc_t | 5.5 Mix_EffectFunc_t
 | MIX_EFFECTSMAXSPEED | 6. Defines
 | Mix_ExpireChannel | 4.3.10 Mix_ExpireChannel
 | Mix_FadeInChannel | 4.3.5 Mix_FadeInChannel
 | Mix_FadeInChannel | 4.4.1 Mix_ReserveChannels
 | Mix_FadeInChannelTimed | 4.3.6 Mix_FadeInChannelTimed
 | Mix_FadeInChannelTimed | 4.4.1 Mix_ReserveChannels
 | Mix_FadeInMusic | 4.5.6 Mix_FadeInMusic
 | Mix_FadeInMusicPos | 4.5.7 Mix_FadeInMusicPos
 | Mix_FadeOutChannel | 4.3.11 Mix_FadeOutChannel
 | Mix_FadeOutGroup | 4.4.8 Mix_FadeOutGroup
 | Mix_FadeOutMusic | 4.5.16 Mix_FadeOutMusic
 | Mix_Fading | 5.4 Mix_Fading
 | Mix_FadingChannel | 4.3.15 Mix_FadingChannel
 | Mix_FadingMusic | 4.5.21 Mix_FadingMusic
 | Mix_FreeChunk | 4.2.8 Mix_FreeChunk
 | Mix_FreeMusic | 4.5.4 Mix_FreeMusic
 | Mix_GetChunk | 4.3.16 Mix_GetChunk
 | Mix_GetChunkDecoder | 4.2.2 Mix_GetChunkDecoder
 | Mix_GetError | 4.1.7 Mix_GetError
 | Mix_GetMusicDecoder | 4.5.2 Mix_GetMusicDecoder
 | Mix_GetMusicHookData | 4.5.22 Mix_GetMusicHookData
 | Mix_GetMusicType | 4.5.18 Mix_GetMusicType
 | Mix_GetNumChunkDecoders | 4.2.1 Mix_GetNumChunkDecoders
 | Mix_GetNumMusicDecoders | 4.5.1 Mix_GetNumMusicDecoders
 | Mix_GroupAvailable | 4.4.5 Mix_GroupAvailable
 | Mix_GroupChannel | 4.4.2 Mix_GroupChannel
 | Mix_GroupChannels | 4.4.3 Mix_GroupChannels
 | Mix_GroupCount | 4.4.4 Mix_GroupCount
 | Mix_GroupNewer | 4.4.7 Mix_GroupNewer
 | Mix_GroupOldest | 4.4.6 Mix_GroupOldest
 | Mix_HaltChannel | 4.3.9 Mix_HaltChannel
 | Mix_HaltGroup | 4.4.9 Mix_HaltGroup
 | Mix_HaltMusic | 4.5.15 Mix_HaltMusic
 | Mix_HookMusic | 4.5.8 Mix_HookMusic
 | Mix_HookMusicFinished | 4.5.17 Mix_HookMusicFinished
 | Mix_Init | 4.1.2 Mix_Init
 | Mix_Linked_Version | 4.1.1 Mix_Linked_Version
 | Mix_LoadMUS | 4.5.3 Mix_LoadMUS
 | Mix_LoadWAV | 4.2.3 Mix_LoadWAV
 | Mix_LoadWAV_RW | 4.2.4 Mix_LoadWAV_RW
 | MIx_MAJOR_VERSION | 6. Defines
 | MIX_MAX_VOLUME | 6. Defines
 | MIX_MINOR_VERSION | 6. Defines
 | Mix_Music | 5.2 Mix_Music
 | Mix_MusicType | 5.3 Mix_MusicType
 | Mix_OpenAudio | 4.1.4 Mix_OpenAudio
 | MIX_PATCHLEVEL | 6. Defines
 | Mix_Pause | 4.3.7 Mix_Pause
 | Mix_Paused | 4.3.14 Mix_Paused
 | Mix_PausedMusic | 4.5.20 Mix_PausedMusic
 | Mix_PauseMusic | 4.5.10 Mix_PauseMusic
 | Mix_PlayChannel | 4.3.3 Mix_PlayChannel
 | Mix_PlayChannel | 4.4.1 Mix_ReserveChannels
 | Mix_PlayChannelTimed | 4.3.4 Mix_PlayChannelTimed
 | Mix_PlayChannelTimed | 4.4.1 Mix_ReserveChannels
 | Mix_Playing | 4.3.13 Mix_Playing
 | Mix_PlayingMusic | 4.5.19 Mix_PlayingMusic
 | Mix_PlayMusic | 4.5.5 Mix_PlayMusic
 | Mix_QuerySpec | 4.1.8 Mix_QuerySpec
 | Mix_QuickLoad_RAW | 4.2.6 Mix_QuickLoad_RAW
 | Mix_QuickLoad_WAV | 4.2.5 Mix_QuickLoad_WAV
 | Mix_Quit | 4.1.3 Mix_Quit
 | Mix_RegisterEffect | 4.6.1 Mix_RegisterEffect
 | Mix_ReserveChannels | 4.4.1 Mix_ReserveChannels
 | Mix_Resume | 4.3.8 Mix_Resume
 | Mix_ResumeMusic | 4.5.11 Mix_ResumeMusic
 | Mix_RewindMusic | 4.5.12 Mix_RewindMusic
 | Mix_SetDistance | 4.6.6 Mix_SetDistance
 | Mix_SetError | 4.1.6 Mix_SetError
 | Mix_SetMusicCMD | 4.5.14 Mix_SetMusicCMD
 | Mix_SetMusicPosition | 4.5.13 Mix_SetMusicPosition
 | Mix_SetPanning | 4.6.5 Mix_SetPanning
 | Mix_SetPosition | 4.6.7 Mix_SetPosition
 | Mix_SetPostMix | 4.6.4 Mix_SetPostMix
 | Mix_SetReverseStereo | 4.6.8 Mix_SetReverseStereo
 | Mix_UnregisterAllEffects | 4.6.3 Mix_UnregisterAllEffects
 | Mix_UnregisterEffect | 4.6.2 Mix_UnregisterEffect
 | Mix_Volume | 4.3.2 Mix_Volume
 | Mix_VolumeChunk | 4.2.7 Mix_VolumeChunk
 | Mix_VolumeMusic | 4.5.9 Mix_VolumeMusic
 | MSB | 7. Glossary
R |  |
 | README | 1. Overview
S |  |
 | sdl-config | 2.2 Compiling
 | SDL_AudioDriverName | 3. Conflicts
 | SDL_CloseAudio | 3. Conflicts
 | SDL_GetAudioStatus | 3. Conflicts
 | SDL_LockAudio | 3. Conflicts
 | SDL_MIXER_MAJOR_VERSION | 6. Defines
 | SDL_MIXER_MINOR_VERSION | 6. Defines
 | SDL_MIXER_PATCHLEVEL | 6. Defines
 | SDL_MIXER_VERSION | 4.1.1 Mix_Linked_Version
 | SDL_OpenAudio | 3. Conflicts
 | SDL_PauseAudio | 3. Conflicts
 | SDL_UnlockAudio | 3. Conflicts

Jump to: B L M R S

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: About this document

About this document

This document was generated on November, 13 2009 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10: Short Table of Contents

Short Table of Contents

1. Overview
2. Getting Started
3. Conflicts
4. Functions
5. Types
6. Defines
7. Glossary
Index

This document was generated on November, 13 2009 using texi2html


SDL_mixer 1.2.10:

Content

1. Overview
2. Getting Started
3. Conflicts
4. Functions
5. Types
6. Defines
7. Glossary
Index


SDL_net 1.2.7: SDL_net 1.2.7

SDL_net 1.2.7

1. Overview The README from the SDL_net distribution

2. Getting Started Using SDL_net

3. Functions | Functions supported by the SDL_net API
4. Types | Types used with the SDL_net API
5. Defines | Defined values/macros in the SDL_net API

6. Glossary Terms used in this document

Index Index of selected words

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: Overview

1. Overview

A Little Bit About Me

I am currently, as I write this document, a programmer for Raytheon. There I do all sorts of communications, network, GUI, and other general programming tasks in C/C++ on the Solaris and sometimes Linux Operating Systems. I have been programming network code at work and in my free time for about 8 years. I find there is always more to learn about network coding, but the rewards for making something comunicate over what can only be called the most chaotic channel of information transfer are sometimes to much fun to ignore. I have coded only a few things in SDL_net that I would call complete projects. However SDL_net does make network coding easier and more portable than anything I could code using just plain BSD sockets. I was happy that I could finally base my code on something that is portable and small enough to be unintrusive. SDL_net does sometimes seem to oversimplify some things, but in the end I found that if I couldn't do it in SDL_net then perhaps I'm not doing something that is worthwhile. Of course I have and will continue to do things that are not so worthwhile perhaps, using SDL_net. Like a Web Server library, and an IRC client library. But I still enjoy making them anyway! So if you are making a game, or doing a school project, or even making a no-fun application, SDL_net is a viable choice in my opinion for almost any of these tasks. If you are interested in multicast and non-TCP/IPv4 networking then SDL_net is not the right thing for you. Everyone else, please make more network games that are fun to play, and portable enough that more people are out there to play with. I, meanwhile, will continue writting documentation and applications and games that will likely become vapourware before they even see the light of day, but I'll be having fun the whole time.

Feel free to contact me: JonathanCAtkins@gmail.com

I am also usually on IRC at irc.freenode.net in the #SDL channel as LIM

This is the README in the SDL_net source archive.

SDL_net 1.2

The latest version of this library is available from:
SDL_net Homepage

This is an example portable network library for use with SDL. It is available under the GNU Library General Public License. The API can be found in the file SDL_net.h This library supports UNIX, Windows, and BeOS. MacOS support is being written.

The demo program is a chat client and server. The chat client requires the sample GUI library available at:
GUIlib Homepage
The chat client connects to the server via TCP, registering itself. The server sends back a list of connected clients, and keeps the client updated with the status of other clients. Every line of text from a client is sent via UDP to every other client.

Note that this isn't necessarily how you would want to write a chat program, but it demonstrates how to use the basic features of the network library.

Enjoy!

-Sam Lantinga and Roy Wood

You may want to look at
Beej's Guide to Network Programming, which explains network programming using BSD sockets. You can apply the knowledge from there while using SDL_net.

And here's a bit of humor for you to look at as you deal with networking terms.

Dr. Suess as a Network Wizard

Gene_Ziegler@Cornell.edu

Here's an easy game to play.
Here's an easy thing to say....

If a packet hits a pocket on a socket on a port,
and the bus is interupted as a very last resort,
and the address of the memory makes your floppy disk abort
then the socket packet pocket has an error to report!

If your cursor finds a menu item followed by a dash,
and the double-clicking icon puts your window in the trash,
and your data is corrupted cause the index doesn't hash,
then your situation's hopeless, and your system's gona crash.

You can't say this? What a shame, sir!
We'll find you another game, sir.

If the label on the cable on the table at your house
says the network is connected to the button on your mouse,
but your packets want to tunnel on another protocol,
that's repeatedly rejected by the printer down the hall,
and your screen is all distorted by the side-effects of gauss,
so your icons in the window are as wavy as a souse,
then you may as well reboot and go out with a bang,
cause as sure as I'm a poet, the sucker's gunna hang!

When the copy of your floppy's getting sloppy on the disk,
and the microcode instructions cause unecessary risc,
then you have to flash your memory and you'll want to RAM your ROM.
quickly turn of your computer and be sure to tell your mom!

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: Getting Started

2. Getting Started

This assumes you have gotten SDL_net and installed it on your system. SDL_net has an INSTALL document in the source distribution to help you get it compiled and installed.

Generally, installation consists of:

./configure
make
make install

You may also want to look at some demonstration code which may be downloaded from:
http://www.jonatkins.org/SDL_net/

2.1 Includes | The include files to use for SDL_net
2.2 Compiling | Using the SDL_net library and header file.

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: Includes

2.1 Includes

To use SDL_net functions in a C/C++ source code file, you must use the SDL_net.h include file:

#include "SDL_net.h"

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: Compiling

2.2 Compiling

To link with SDL_net you should use sdl-config to get the required SDL compilation options. After that, compiling with SDL_net is quite easy.
Note: Some systems may not have the SDL_net library and include file in the same place as the SDL library and includes are located, in that case you will need to add more -I and -L paths to these command lines.

Simple Example for compiling an object file:

cc -c `sdl-config --cflags` mysource.c

Simple Example for compiling an object file:

cc -o myprogram mysource.o `sdl-config --libs` -lSDL_net

Now myprogram is ready to run.

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: Functions

3. Functions

These are the functions in the SDL_net API.

3.1 General | API activation, versioning, and byte order helpers
3.2 Name Resolution | Hostname and numeric IP lookup (IPaddress functions)
3.3 TCP Sockets | Working with TCP connections
3.4 UDP Sockets | Working with UDP semi-connections
3.5 UDP Packets | Working with the UDPpacket type
3.6 Socket Sets | Working on demand with sockets

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: General

3.1 General

The basic API startup, cleanup and versioning methods, along with a few network byte order data helpers.

Info
3.1.1 SDLNet_Linked_Version Get version number
Activation
3.1.2 SDLNet_Init | Start up SDL_net functionality
3.1.3 SDLNet_Quit | Stop SDL_net functionality
Errors
3.1.4 SDLNet_GetError Get the current error string
Data Byte Order Helpers
3.1.5 SDLNet_Write16 | Put a 16bit number in network ordered data
3.1.6 SDLNet_Write32 | Put a 32bit number in network ordered data
3.1.7 SDLNet_Read16 | Get a 16bit number from network ordered data
3.1.8 SDLNet_Read32 | Get a 32bit number from network ordered data

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_Linked_Version

3.1.1 SDLNet_Linked_Version

const SDL_version *SDLNet_Linked_Version()
void SDL_NET_VERSION(SDL_version *compile_version)

This works similar to SDL_Linked_Version and SDL_VERSION.
Using these you can compare the runtime version to the version that you compiled with.
No prior library initialization is needed to call these functions/macros.

SDL_version compile_version;
const SDL_version *link_version=SDLNet_Linked_Version();
SDL_NET_VERSION(&compile_version);
printf("compiled with SDL_net version: %d.%d.%d\n",
        compile_version.major,
        compile_version.minor,
        compile_version.patch);
printf("running with SDL_net version: %d.%d.%d\n",
        link_version->major,
        link_version->minor,
        link_version->patch);

See Also:
3.1.2 SDLNet_Init

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_Init

3.1.2 SDLNet_Init

int SDLNet_Init()

Initialize the network API.
This must be called before using other functions in this library.
SDL must be initialized before this call.

Returns: 0 on success, -1 on errors

if(SDL_Init(0)==-1) {
    printf("SDL_Init: %s\n", SDL_GetError());
    exit(1);
}
if(SDLNet_Init()==-1) {
    printf("SDLNet_Init: %s\n", SDLNet_GetError());
    exit(2);
}

See Also:
3.1.3 SDLNet_Quit

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_Quit

3.1.3 SDLNet_Quit

void SDLNet_Quit()

Shutdown and cleanup the network API.
After calling this all sockets are closed, and the SDL_net functions should not be used. You may, of course, use SDLNet_Init to use the functionality again.

SDLNet_Quit();
// you could SDL_Quit(); here...or not.

See Also:
3.1.2 SDLNet_Init

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_GetError

3.1.4 SDLNet_GetError

char *SDLNet_GetError()

This is the same as SDL_GetError, which returns the last error set as a string which you may use to tell the user what happened when an error status has been returned from an SDLNet_function.

Returns: a char pointer (string) containing a humam readble version or the reason for the last error that occured.

printf("Oh My Goodness, an error : %s", SDLNet_GetError());

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_Write16

3.1.5 SDLNet_Write16

void SDLNet_Write16(Uint16 value, void *area)

value
The 16bit number to put into the area buffer
area
The pointer into a data buffer, at which to put the number

Put the 16bit (a short on 32bit systems) value into the data buffer area in network byte order. This helps avoid byte order differences between two systems that are talking over the network. The value can be a signed number, the unsigned parameter type doesn't affect the data. The area pointer need not be at the beginning of a buffer, but must have at least 2 bytes of space left, including the byte currently pointed at.

// put my number into a data buffer to prepare for sending to a remote host
char data[1024];
Sint16 number=12345;
SDLNet_Write16((Uint16)number,data);

See Also:
3.1.7 SDLNet_Read16, 3.1.6 SDLNet_Write32

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_Write32

3.1.6 SDLNet_Write32

void SDLNet_Write32(Uint32 value, void *area)

value
The 32bit number to put into the area buffer
area
The pointer into a data buffer, at which to put the number

Put the 32bit (a long on 32bit systems) value into the data buffer area in network byte order. This helps avoid byte order differences between two systems that are talking over the network. The value can be a signed number, the unsigned parameter type doesn't affect the data. The area pointer need not be at the beginning of a buffer, but must have at least 4 bytes of space left, including the byte currently pointed at.

// put my number into a data buffer to prepare for sending to a remote host
char data[1024];
Uint32 number=0xDEADBEEF;
SDLNet_Write32(number,data);

See Also:
3.1.8 SDLNet_Read32, 3.1.5 SDLNet_Write16

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_Read16

3.1.7 SDLNet_Read16

Uint16 SDLNet_Read16(void *area)

area
The pointer into a data buffer, at which to get the number from

Get a 16bit (a short on 32bit systems) value from the data buffer area which is in network byte order. This helps avoid byte order differences between two systems that are talking over the network. The returned value can be a signed number, the unsigned parameter type doesn't affect the data. The area pointer need not be at the beginning of a buffer, but must have at least 2 bytes of space left, including the byte currently pointed at.

// get a number from a data buffer to use on this host
//char *ptr; //this points into a previously received data buffer
Sint16 number;
number=(Sint16) SDLNet_Read16(ptr);
// number is now in your hosts byte order, ready to use.

See Also:
3.1.5 SDLNet_Write16, 3.1.8 SDLNet_Read32

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_Read32

3.1.8 SDLNet_Read32

Uint32 SDLNet_Read32(void *area)

area
The pointer into a data buffer, at which to get the number from

Get a 32bit (a long on 32bit systems) value from the data buffer area which is in network byte order. This helps avoid byte order differences between two systems that are talking over the network. The returned value can be a signed number, the unsigned parameter type doesn't affect the data. The area pointer need not be at the beginning of a buffer, but must have at least 4 bytes of space left, including the byte currently pointed at.

// get a number from a data buffer to use on this host
//char *ptr; //this points into a previously received data buffer
Uint32 number;
number=SDLNet_Read32(ptr);
// number is now in your hosts byte order, ready to use.

See Also:
3.1.6 SDLNet_Write32, 3.1.7 SDLNet_Read16

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: Name Resolution

3.2 Name Resolution

These functions are used to resolve hostnames and numerical IPv4 Address to each other.

3.2.1 SDLNet_ResolveHost
3.2.2 SDLNet_ResolveIP

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_ResolveHost

3.2.1 SDLNet_ResolveHost

int SDLNet_ResolveHost(IPaddress *address, const char *host, Uint16 port)

address
This points to the IPaddress that will be filled in. It doesn't need to be set before calling this, but it must be allocated in memory.
host
For connecting to a server, this is the hostname or IP in a string.
For becoming a server, this is NULL. If you do use NULL, all network interfaces would be listened to for incoming connections, using the INADDR_ANY address.
port
For connecting to a server, this is the the servers listening port number.
For becoming a server, this is the port to listen on.
If you are just doing Domain Name Resolution functions, this can be 0.

Resolve the string host, and fill in the IPaddress pointed to by address with the resolved IP and the port number passed in through port.
This is the best way to fill in the IPaddress struct for later use. This function does not actually open any sockets, it is used to prepare the arguments for the socket opening functions.
WARNING: this function will put the host and port into Network Byte Order into the address fields, so make sure you pass in the data in your hosts byte order. (normally not an issue)

Returns: 0 on success. -1 on errors, plus address.host will be INADDR_NONE. An error would likely be that the address could not be resolved.

For a server listening on all interfaces, on port 1234:

// create a server type IPaddress on port 1234
IPaddress ipaddress;
SDLNet_ResolveHost(&ipaddress, NULL, 1234);

For a client connecting to "host.domain.ext", at port 1234:

// create an IPaddress for host name "host.domain.ext" on port 1234
// this is used by a client
IPaddress ipaddress;
SDLNet_ResolveHost(&ipaddress, "host.domain.ext", 1234);

See Also:
3.2.2 SDLNet_ResolveIP, 4.1 IPaddress

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_ResolveIP

3.2.2 SDLNet_ResolveIP

const char *SDLNet_ResolveIP(IPaddress *address)

address
This points to the IPaddress that will be resolved to a host name. The address->port is ignored.

Resolve the IPv4 numeric address in address->host, and return the hostname as a string.

Returns: a valid char pointer (string) on success. the returned hostname will have host and domain, as in "host.domain.ext". NULL is returned on errors, such as when it's not able to resolve the host name. The returned pointer is not to be freed. Each time you call this function the previous pointer's data will change to the new value, so you may have to copy it into a local buffer to keep it around longer.

// resolve the host name of the address in ipaddress
//IPaddress ipaddress;
char *host;
if(!(host=SDLNet_ResolveIP(&ipaddress))) {
    printf("SDLNet_ResolveIP: %s\n", SDLNet_GetError());
    exit(1);
}

See Also:
3.2.1 SDLNet_ResolveHost, 4.1 IPaddress

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: TCP Sockets

3.3 TCP Sockets

These functions are used to work with TCP Sockets. TCP is used with a full connection, whereas UDP is connectionless. TCP also ensures that all packets reach the destionation (when possible). TCP also ensures that packets are received in the same order as sent.

General
3.3.1 SDLNet_TCP_Open | Open a TCP client or server socket
3.3.2 SDLNet_TCP_Close | Close a TCP socket
Server
3.3.3 SDLNet_TCP_Accept Accept a connection on a server socket
Information
3.3.4 SDLNet_TCP_GetPeerAddress Get the remote host address and port number
Input/Output
3.3.5 SDLNet_TCP_Send | Send data over a connected socket
3.3.6 SDLNet_TCP_Recv | Receive data from a connected socket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_TCP_Open

3.3.1 SDLNet_TCP_Open

TCPsocket SDLNet_TCP_Open(IPaddress *ip)

ip
This points to the IPaddress that contains the resolved IP address and port number to use.

Connect to the host and port contained in ip using a TCP connection.
If the host is INADDR_ANY, then only the port number is used, and a socket is created that can be used to later accept incoming TCP connections.

Returns: a valid TCPsocket on success, which indicates a successful connection has been established, or a socket has been created that is valid to accept incoming TCP connections. NULL is returned on errors, such as when it's not able to create a socket, or it cannot connect to host and/or port contained in ip.

// connect to localhost at port 9999 using TCP (client)
IPaddress ip;
TCPsocket tcpsock;

if(SDLNet_ResolveHost(&ip,"localhost",9999)==-1) {
    printf("SDLNet_ResolveHost: %s\n", SDLNet_GetError());
    exit(1);
}

tcpsock=SDLNet_TCP_Open(&ip);
if(!tcpsock) {
    printf("SDLNet_TCP_Open: %s\n", SDLNet_GetError());
    exit(2);
}

// create a listening TCP socket on port 9999 (server)
IPaddress ip;
TCPsocket tcpsock;

if(SDLNet_ResolveHost(&ip,NULL,9999)==-1) {
    printf("SDLNet_ResolveHost: %s\n", SDLNet_GetError());
    exit(1);
}

tcpsock=SDLNet_TCP_Open(&ip);
if(!tcpsock) {
    printf("SDLNet_TCP_Open: %s\n", SDLNet_GetError());
    exit(2);
}

See Also:
3.3.3 SDLNet_TCP_Accept, 3.3.2 SDLNet_TCP_Close, 4.1 IPaddress, 4.2 TCPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_TCP_Close

3.3.2 SDLNet_TCP_Close

void SDLNet_TCP_Close(TCPsocket sock)

sock
A valid TCPsocket. This can be a server or client type socket.

This shutsdown, disconnects, and closes the TCPsocket sock.
After this, you can be assured that this socket is not in use anymore. You can reuse the sock variable after this to open a new connection with SDLNet_TCP_Open. Do not try to use any other functions on a closed socket, as it is now invalid.

Returns: nothing, this always succeeds for all we need to know.

// close the connection on sock
//TCPsocket sock;

SDLNet_TCP_Close(sock);

See Also:
3.3.1 SDLNet_TCP_Open, 4.2 TCPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_TCP_Accept

3.3.3 SDLNet_TCP_Accept

TCPsocket SDLNet_TCP_Accept(TCPsocket server)

server
This is the server TCPsocket which was previously created by
SDLNet_TCP_Open.

Accept an incoming connection on the server TCPsocket.
Do not use this function on a connected socket. Server sockets are never connected to a remote host. What you get back is a new TCPsocket that is connected to the remote host.
This is a non-blocking call, so if no connections are there to be accepted, you will get a NULL TCPsocket and the program will continue going.

Returns: a valid TCPsocket on success, which indicates a successful connection has been established. NULL is returned on errors, such as when it's not able to create a socket, or it cannot finish connecting to the originating host and port. There also may not be a connection attempt in progress, so of course you cannot accept nothing, and you get a NULL in this case as well.

// accept a connection coming in on server_tcpsock
TCPsocket new_tcpsock;

new_tcpsock=SDLNet_TCP_Accept(server_tcpsock);
if(!new_tcpsock) {
    printf("SDLNet_TCP_Accept: %s\n", SDLNet_GetError());
}
else {
    // communicate over new_tcpsock
}

See Also:
3.3.1 SDLNet_TCP_Open, 3.3.4 SDLNet_TCP_GetPeerAddress, 3.3.2 SDLNet_TCP_Close, 4.2 TCPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_TCP_GetPeerAddress

3.3.4 SDLNet_TCP_GetPeerAddress

IPaddress *SDLNet_TCP_GetPeerAddress(TCPsocket sock)

sock
This is a valid TCPsocket.

Get the Peer's (the other side of the connection, the remote side, not the local side) IP address and port number.

Returns: an IPaddress. NULL is returned on errors, or when sock is a server socket.

// get the remote IP and port
//TCPsocket new_tcpsock;
IPaddress *remote_ip;

remote_ip=SDLNet_TCP_GetPeerAddress(new_tcpsock);
if(!remote_ip) {
    printf("SDLNet_TCP_GetPeerAddress: %s\n", SDLNet_GetError());
    printf("This may be a server socket.\n");
}
else {
    // print the info in IPaddress or something else...
}

See Also:
3.3.1 SDLNet_TCP_Open, 3.3.3 SDLNet_TCP_Accept, 4.1 IPaddress, 4.2 TCPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_TCP_Send

3.3.5 SDLNet_TCP_Send

int SDLNet_TCP_Send(TCPsocket sock, const void *data, int len)

sock
This is a valid, connected, TCPsocket.
data
This is a pointer to the data to send over sock.
len
This is the length (in bytes) if the data.

Send data of length len over the socket sock.
This routine is not used for server sockets.

Returns: the number of bytes sent. If the number returned is less than len, then an error occured, such as the client disconnecting.

// send a hello over sock
//TCPsocket sock;
int len,result;
char *msg="Hello!";

len=strlen(msg)+1; // add one for the terminating NULL
result=SDLNet_TCP_Send(sock,msg,len);
if(result<len) {
    printf("SDLNet_TCP_Send: %s\n", SDLNet_GetError());
    // It may be good to disconnect sock because it is likely invalid now.
}

See Also:
3.3.6 SDLNet_TCP_Recv, 3.3.3 SDLNet_TCP_Accept, 3.3.1 SDLNet_TCP_Open, 3.3.4 SDLNet_TCP_GetPeerAddress, 3.3.2 SDLNet_TCP_Close, 4.2 TCPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_TCP_Recv

3.3.6 SDLNet_TCP_Recv

int SDLNet_TCP_Recv(TCPsocket sock, void *data, int maxlen)

sock
This is a valid, connected, TCPsocket.
data
This is a pointer to the buffer that receives the data from sock.
maxlen
This is the maximum length (in bytes) that will be read into data.

Receive data of exactly length maxlen bytes from the socket sock, into the memory pointed to by data.
This routine is not used for server sockets.
Unless there is an error, or the connection is closed, the buffer will read maxlen bytes. If you read more than is sent from the other end, then it will wait until the full requested length is sent, or until the connection is closed from the other end.
You may have to read 1 byte at a time for some applications, for instance, text applications where blocks of text are sent, but you want to read line by line. In that case you may want to find the newline characters yourself to break the lines up, instead of reading some inordinate amount of text which may contain many lines, or not even a full line of text.

Returns: the number of bytes received. If the number returned is less than or equal to zero, then an error occured, or the remote host has closed the connection.

// receive some text from sock
//TCPsocket sock;
#define MAXLEN 1024
int result;
char msg[MAXLEN];

result=SDLNet_TCP_Recv(sock,msg,MAXLEN);
if(result<=0) {
    // An error may have occured, but sometimes you can just ignore it
    // It may be good to disconnect sock because it is likely invalid now.
}
printf("Received: \"%s\"\n",msg);

See Also:
3.3.5 SDLNet_TCP_Send, 3.3.3 SDLNet_TCP_Accept, 3.3.1 SDLNet_TCP_Open, 3.3.4 SDLNet_TCP_GetPeerAddress, 3.3.2 SDLNet_TCP_Close, 4.2 TCPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: UDP Sockets

3.4 UDP Sockets

These functions are used to work with UDP Sockets.
UDP is connectionless, but can be used as if it is connected, in the sense that you don't have to address every outgoing packet if you don't want to. This is done by binding a socket to remote IP address and port pairs.
UDP has no delivery guarantees, each packet has a chance of never getting to the destination.
UDP packets may also be received completely out of order, as compared to the order of sending them.
All these seeming bad qualities are made up for in speed. UDP is faster than TCP, and so many games and speed sensitive applications, which may also be sending redundant data anyways, such as a game state, prefer to use UDP for the speed benefits.

SDL_net has a concept of channels, which help you to matchup packets to specific clients easier. These channel numbers are not transmitted in the UDP packet data, but rather when a UDP socket receives or sends packets, a channel number may be used instead of an IPaddress to refer to the source or destination. You might prefer not to use channels at all, which is fine. SDL_net provides them only as an optional convenience.

General
3.4.1 SDLNet_UDP_Open | Create a UDP socket
3.4.2 SDLNet_UDP_Close | Close and free a UDP socket
Channel Binding
3.4.3 SDLNet_UDP_Bind | Assign an IP address number to a socket channel
3.4.4 SDLNet_UDP_Unbind | Remove all assigned IP addresses from a socket channel
3.4.5 SDLNet_UDP_GetPeerAddress | Get the assigned IP address for a socket channel or get the port you opened the socket with
Single UDPpacket
3.4.6 SDLNet_UDP_Send | Send a UDPpacket
3.4.7 SDLNet_UDP_Recv | Receive into a UDPpacket
Many UDPpackets in a vector (array)
3.4.8 SDLNet_UDP_SendV | Send a UDPpacket vector
3.4.9 SDLNet_UDP_RecvV | Receive into a UDPpacket vector

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_UDP_Open

3.4.1 SDLNet_UDP_Open

UDPsocket SDLNet_UDP_Open(Uint16 port)

port
This is the port number (in native byte order) on which to receive UDP packets. Most servers will want to use a known port number here so that clients can easily communicate with the server. This can also be zero, which then opens an anonymous unused port number, to most likely be used to send UDP packets from.

Open a socket to be used for UDP packet sending and/or receiving.
If a non-zero port is given it will be used, otherwise any open port number will be used automatically.
Unlike TCP sockets, this socket does not require a remote host IP to connect to, this is because UDP ports are never actually connected like TCP ports are.
This socket is able to send and receive directly after this simple creation.

Returns: a valid UDPsocket on success. NULL is returned on errors, such as when it's not able to create a socket, or it cannot assign the non-zero port as requested.

Note that below I say server, but clients may also open a specific port, though it is prefered that a client be more flexible, given that the port may be already allocated by another process, such as a server. In such a case you will not be able to open the socket, and your program will be stuck, so it is better to just use whatever port you are given by using a specified port of zero. Then the client will always work. The client can inform the server what port to talk back to, or the server can just look at the source of the packets it is receiving to know where to respond to.

// create a UDPsocket on port 6666 (server)
UDPsocket udpsock;

udpsock=SDLNet_UDP_Open(6666);
if(!udpsock) {
    printf("SDLNet_UDP_Open: %s\n", SDLNet_GetError());
    exit(2);
}

// create a UDPsocket on any available port (client)
UDPsocket udpsock;

udpsock=SDLNet_UDP_Open(0);
if(!udpsock) {
    printf("SDLNet_UDP_Open: %s\n", SDLNet_GetError());
    exit(2);
}

See Also:
3.4.2 SDLNet_UDP_Close, 4.3 UDPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_UDP_Close

3.4.2 SDLNet_UDP_Close

void SDLNet_UDP_Close(UDPsocket sock)

sock
A valid UDPsocket to shutdown, close, and free.

Shutdown, close, and free a UDPsocket.
Don't use the UDPsocket after calling this, except to open a new one.

Returns: nothing, this always succeeds.

// unbind all addresses on the UDPsocket channel 0
//UDPsocket udpsock;

SDLNet_UDP_Close(udpsock);
udpsock=NULL; //this helps us know that this UDPsocket is not valid anymore

See Also:
3.4.1 SDLNet_UDP_Open, 4.3 UDPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_UDP_Bind

3.4.3 SDLNet_UDP_Bind

int SDLNet_UDP_Bind(UDPsocket sock, int channel, IPaddress *address)

sock
the UDPsocket on which to assign the address.
channel
The channel to assign address to. This should be less than
SDLNET_MAX_UDPCHANNELS. If -1 is used, then the first unbound channel will be used, this should only be used for incomming packet filtering, as it will find the first channel with less than SDLNET_MAX_UDPADDRESSES assigned to it and use that one.
address
The resolved IPaddress to assign to the socket's channel. The host and port are both used.
It is not helpful to bind 0.0.0.0 to a channel.

Bind an address to a channel on a socket.
Incoming packets are only allowed from bound addresses for the socket channel.
All outgoing packets on that channel, regardless of the packets internal address, will attempt to send once on each bound address on that channel.
You may assign up to SDLNET_MAX_UDPADDRESSES to each channel.

Returns: The channel number that was bound. -1 is returned on errors, such as no free channels, or this channel has SDLNET_MAX_UDPADDRESSES already assigned to it, or you have used a channel higher or equal to SDLNET_MAX_UDPCHANNELS, or lower than -1.

// Bind address to the first free channel
//UDPsocket udpsock;
//IPaddress *address;
int channel;

channel=SDLNet_UDP_Bind(udpsock, -1, address);
if(channel==-1) {
    printf("SDLNet_UDP_Bind: %s\n", SDLNet_GetError());
    // do something because we failed to bind
}

See Also:
3.4.4 SDLNet_UDP_Unbind, 3.4.5 SDLNet_UDP_GetPeerAddress, 3.4.1 SDLNet_UDP_Open, 4.1 IPaddress, 4.3 UDPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_UDP_Unbind

3.4.4 SDLNet_UDP_Unbind

void SDLNet_UDP_Unbind(UDPsocket sock, int channel)

sock
A valid UDPsocket to unbind addresses from.
channel
The channel to unbind the addresses from in the UDPsocket.

This removes all previously assigned (bound) addresses from a socket channel.
After this you may bind new addresses to the socket channel.

Returns: nothing, this always succeeds.

// unbind all addresses on the UDPsocket channel 0
//UDPsocket udpsock;

SDLNet_UDP_Unbind(udpsock, 0);

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.2 SDLNet_UDP_Close, 4.3 UDPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_UDP_GetPeerAddress

3.4.5 SDLNet_UDP_GetPeerAddress

IPaddress *SDLNet_UDP_GetPeerAddress(UDPsocket sock, int channel)

sock
A valid UDPsocket that probably has an address assigned to the channel.
channel
The channel to get the primary address from in the socket. This may also be -1 to get the port which this socket is bound to on the local computer.

Get the primary address assigned to this channel. Only the first bound address is returned.
When channel is -1, get the port that this socket is bound to on the local computer, this only means something if you opened the socket with a specific port number.
Do not free the returned IPaddress pointer.

Returns: a pointer to an IPaddress. NULL is returned for unbound channels and on any errors.

// get the primary address bound to UDPsocket channel 0
//UDPsocket udpsock;
IPaddress *address;

address=SDLNet_UDP_GetPeerAddress(udpsock, 0);
if(!address) {
    printf("SDLNet_UDP_GetPeerAddress: %s\n", SDLNet_GetError());
    // do something because we failed to get the address
}
else {
    // perhaps print out address->host and address->port
}

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.4 SDLNet_UDP_Unbind, 4.1 IPaddress, 4.3 UDPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_UDP_Send

3.4.6 SDLNet_UDP_Send

int SDLNet_UDP_Send(UDPsocket sock, int channel, UDPpacket *packet)

sock
A valid UDPsocket.
channel
what channel to send packet on.
packet
The packet to send.

Send packet using the specified socket sock, use ing the specified channel or else the packet's address.
If channel is not -1 then the packet is sent to all the socket channels bound addresses. If socket sock's channel is not bound to any destinations, then the packet is not sent at all!
If the channel is -1, then the packet's address is used as the destination.
Don't forget to set the length of the packet in the len element of the packet you are sending! Note: the packet->channel will be set to the channel passed in to this function. Note: The maximum size of the packet is limited by the MTU (Maximum Transfer Unit) of the transport medium. It can be as low as 250 bytes for some PPP links, and as high as 1500 bytes for ethernet. Beyond that limit the packet will fragment, and make delivery more and more unreliable as lost fragments cause the whole packet to be discarded.

Returns: The number of destinations sent to that worked. 0 is returned on errors.
Note that since a channel can point to multiple destinations, there should be just as many packets sent, so dont assume it will always return 1 on success. Unfortunately there's no way to get the number of destinations bound to a channel, so either you have to remember the number bound, or just test for the zero return value indicating all channels failed.

// send a packet using a UDPsocket, using the packet's channel as the channel
//UDPsocket udpsock;
//UDPpacket *packet;
int numsent;

numsent=SDLNet_UDP_Send(udpsock, packet->channel, packet);
if(!numsent) {
    printf("SDLNet_UDP_Send: %s\n", SDLNet_GetError());
    // do something because we failed to send
    // this may just be because no addresses are bound to the channel...
}

Here's a way of sending one packet using it's internal channel setting.
This is actually what SDLNet_UDP_Send ends up calling for you.

// send a packet using a UDPsocket, using the packet's channel as the channel
//UDPsocket udpsock;
//UDPpacket *packet;
int numsent;

numsent=SDLNet_UDP_SendV(sock, &packet, 1);
if(!numsent) {
    printf("SDLNet_UDP_SendV: %s\n", SDLNet_GetError());
    // do something because we failed to send
    // this may just be because no addresses are bound to the channel...
}

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.8 SDLNet_UDP_SendV, 3.4.7 SDLNet_UDP_Recv, 3.4.9 SDLNet_UDP_RecvV, 4.4 UDPpacket, 4.3 UDPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_UDP_Recv

3.4.7 SDLNet_UDP_Recv

int SDLNet_UDP_Recv(UDPsocket sock, UDPpacket *packet)

sock
A valid UDPsocket.
packet
The packet to receive into.

Receive a packet on the specified sock socket.
The packet you pass in must have enough of a data size allocated for the incoming packet data to fit into. This means you should have knowledge of your size needs before trying to receive UDP packets.
The packet will have it's address set to the remote sender's address.
The socket's channels are checked in highest to lowest order, so if an address is bound to multiple channels, the highest channel with the source address bound will be retreived before the lower bound channels. So, the packets channel will also be set to the highest numbered channel that has the remote address and port assigned to it. Otherwise the channel will -1, which you can filter out easily if you want to ignore unbound source address.
Note that the local and remote channel numbers do not have to, and probably won't, match, as they are only local settings, they are not sent in the packet.
This is a non-blocking call, meaning if there's no data ready to be received the function will return.

Returns: 1 is returned when a packet is received. 0 is returned when no packets are received. -1 is returned on errors.

// try to receive a waiting udp packet
//UDPsocket udpsock;
UDPpacket packet;
int numrecv;

numrecv=SDLNet_UDP_Recv(udpsock, &packet);
if(numrecv) {
    // do something with packet
}

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.6 SDLNet_UDP_Send, 3.4.8 SDLNet_UDP_SendV, 3.4.9 SDLNet_UDP_RecvV, 4.4 UDPpacket, 4.3 UDPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_UDP_SendV

3.4.8 SDLNet_UDP_SendV

int SDLNet_UDP_SendV(UDPsocket sock, UDPpacket **packetV, int npackets)

sock
A valid UDPsocket.
packetV
The vector of packets to send.
npackets
number of packets in the packetV vector to send.

Send npackets of packetV using the specified sock socket.
Each packet is sent in the same way as in SDLNet_UDP_Send (see section 3.4.6 SDLNet_UDP_Send).
Don't forget to set the length of the packets in the len element of the packets you are sending!

Returns: The number of destinations sent to that worked, for each packet in the vector, all summed up. 0 is returned on errors.

// send a vector of 10 packets using UDPsocket
//UDPsocket udpsock;
//UDPpacket **packetV;
int numsent;

numsent=SDLNet_UDP_SendV(udpsock, packetV, 10);
if(!numsent) {
    printf("SDLNet_UDP_SendV: %s\n", SDLNet_GetError());
    // do something because we failed to send
    // this may just be because no addresses are bound to the channels...
}

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.6 SDLNet_UDP_Send, 3.4.7 SDLNet_UDP_Recv, 3.4.9 SDLNet_UDP_RecvV, 4.4 UDPpacket, 4.3 UDPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_UDP_RecvV

3.4.9 SDLNet_UDP_RecvV

int SDLNet_UDP_RecvV(UDPsocket sock, UDPpacket **packetV)

sock
A valid UDPsocket.
packet
The packet to receive into.

Receive into a packet vector on the specified socket sock.
packetV is a NULL terminated array. Packets will be received until the NULL is reached, or there are none ready to be received.
This call is otherwise the same as SDLNet_UDP_Recv (see section 3.4.7 SDLNet_UDP_Recv).

Returns: the number of packets received. 0 is returned when no packets are received. -1 is returned on errors.

// try to receive some waiting udp packets
//UDPsocket udpsock;
//UDPpacket **packetV;
int numrecv, i;

numrecv=SDLNet_UDP_RecvV(udpsock, &packetV);
if(numrecv==-1) {
    // handle error, perhaps just print out the SDL_GetError string.
}
for(i=0; i<numrecv; i++) {
    // do something with packetV[i]
}

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.6 SDLNet_UDP_Send, 3.4.8 SDLNet_UDP_SendV, 3.4.7 SDLNet_UDP_Recv, 4.4 UDPpacket, 4.3 UDPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: UDP Packets

3.5 UDP Packets

These functions are used to work with the UDPpacket type. This type is used with UDP sockets to transmit and receive data.

Single UDPpacket
3.5.1 SDLNet_AllocPacket | Allocate a new UDP packet with a data buffer
3.5.2 SDLNet_ResizePacket | Resize the data buffer in a UDPpacket
3.5.3 SDLNet_FreePacket | Free a previously allocated UDPpacket
Many UDPpackets in a vector (array)
3.5.4 SDLNet_AllocPacketV | Allocate a vector of UDPpackets
3.5.5 SDLNet_FreePacketV | Free a vector of UDPpackets

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_AllocPacket

3.5.1 SDLNet_AllocPacket

UDPpacket *SDLNet_AllocPacket(int size)

size
Size, in bytes, of the data buffer to be allocated in the new UDPpacket.
Zero is invalid.

Create (via malloc) a new UDPpacket with a data buffer of size bytes.
The new packet should be freed using SDLNet_FreePacket when you are done using it.

Returns: a pointer to a new empty UDPpacket. NULL is returned on errors, such as out-of-memory.

// create a new UDPpacket to hold 1024 bytes of data
UDPpacket *packet;

packet=SDLNet_AllocPacket(1024);
if(!packet) {
    printf("SDLNet_AllocPacket: %s\n", SDLNet_GetError());
    // perhaps do something else since you can't make this packet
}
else {
    // do stuff with this new packet
    // SDLNet_FreePacket this packet when finished with it
}

See Also:
3.5.4 SDLNet_AllocPacketV, 3.5.2 SDLNet_ResizePacket, 3.5.3 SDLNet_FreePacket, 3.4.6 SDLNet_UDP_Send, 3.4.8 SDLNet_UDP_SendV, 4.4 UDPpacket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_ResizePacket

3.5.2 SDLNet_ResizePacket

int SDLNet_ResizePacket(UDPpacket *packet, int size)

packet
A pointer to the UDPpacket to be resized.
size
The new desired size, in bytes, of the data buffer to be allocated in the UDPpacket.
Zero is invalid.

Resize a UDPpackets data buffer to size bytes. The old data buffer will not be retained, so the new buffer is invalid after this call.

Returns: the new size of the data in the packet. If the number returned is less than what you asked for, that's an error.

// Resize a UDPpacket to hold 2048 bytes of data
//UDPpacket *packet;
int newsize;

newsize=SDLNet_ResizePacket(packet, 2048);
if(newsize<2048) {
    printf("SDLNet_ResizePacket: %s\n", SDLNet_GetError());
    // perhaps do something else since you didn't get the buffer you wanted
}
else {
    // do stuff with the resized packet
}

See Also:
3.5.1 SDLNet_AllocPacket, 3.5.4 SDLNet_AllocPacketV, 3.5.3 SDLNet_FreePacket, 4.4 UDPpacket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_FreePacket

3.5.3 SDLNet_FreePacket

void SDLNet_FreePacket(UDPpacket *packet)

packet
A pointer to the UDPpacket to be freed from memory.

Free a UDPpacket from memory. Do not use this UDPpacket after this function is called on it.

Returns: nothing, this always succeeds.

// Free a UDPpacket
//UDPpacket *packet;

SDLNet_FreePacket(packet);
packet=NULL; //just to help you know that it is freed

See Also:
3.5.1 SDLNet_AllocPacket, 3.5.4 SDLNet_AllocPacketV, 3.5.5 SDLNet_FreePacketV, 3.5.2 SDLNet_ResizePacket, 4.4 UDPpacket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_AllocPacketV

3.5.4 SDLNet_AllocPacketV

UDPpacket **SDLNet_AllocPacketV(int howmany, int size)

howmany
The number of UDPpackets to allocate.
size
Size, in bytes, of the data buffers to be allocated in the new UDPpackets.
Zero is invalid.

Create (via malloc) a vector of new UDPpackets, each with data buffers of size bytes. The new packet vector should be freed using SDLNet_FreePacketV when you are done using it. The returned vector is one entry longer than requested, for a terminating NULL.

Returns: a pointer to a new empty UDPpacket vector. NULL is returned on errors, such as out-of-memory.

// create a new UDPpacket vector to hold 1024 bytes of data in 10 packets
UDPpacket **packetV;

packetV=SDLNet_AllocPacketV(10, 1024);
if(!packetV) {
    printf("SDLNet_AllocPacketV: %s\n", SDLNet_GetError());
    // perhaps do something else since you can't make this packet
}
else {
    // do stuff with this new packet vector
    // SDLNet_FreePacketV this packet vector when finished with it
}

See Also:
3.5.1 SDLNet_AllocPacket, 3.5.3 SDLNet_FreePacket, 3.5.5 SDLNet_FreePacketV, 3.5.2 SDLNet_ResizePacket, 4.4 UDPpacket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_FreePacketV

3.5.5 SDLNet_FreePacketV

void SDLNet_FreePacketV(UDPpacket **packetV)

packetV
A pointer to the UDPpacket vector to be freed from memory.

Free a UDPpacket vector from memory. Do not use this UDPpacket vector, or any UDPpacket in it, after this function is called on it.

Returns: nothing, this always succeeds.

// Free a UDPpacket vector
//UDPpacket **packetV;

SDLNet_FreePacketV(packetV);
packetV=NULL; //just to help you know that it is freed

See Also:
3.5.4 SDLNet_AllocPacketV, 3.5.1 SDLNet_AllocPacket, 3.5.3 SDLNet_FreePacket, 3.5.2 SDLNet_ResizePacket, 4.4 UDPpacket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: Socket Sets

3.6 Socket Sets

These functions are used to work with multiple sockets. They allow you to determine when a socket has data or a connection waiting to be processed. This is analogous to polling, or the select function.

General
3.6.1 SDLNet_AllocSocketSet | Create a new socket set
3.6.2 SDLNet_FreeSocketSet | Free a socket set
Setup
3.6.3 SDLNet_AddSocket | Add a socket to a socket set
3.6.4 SDLNet_DelSocket | Remove a socket from a socket set
Activity Checking
3.6.5 SDLNet_CheckSockets | Check and wait for sockets in a set to have activity
3.6.6 SDLNet_SocketReady | See if a socket has activity

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_AllocSocketSet

3.6.1 SDLNet_AllocSocketSet

SDLNet_SocketSet SDLNet_AllocSocketSet(int maxsockets)

maxsockets
The maximum number of sockets you will want to watch.

Create a socket set that will be able to watch up to maxsockets number of sockets. The same socket set can be used for both UDP and TCP sockets.

Returns: A new, empty, SDLNet_SocketSet. NULL is returned on errors, such as out-of-memory.

// Create a socket set to handle up to 16 sockets
SDLNet_SocketSet set;

set=SDLNet_AllocSocketSet(16);
if(!set) {
    printf("SDLNet_AllocSocketSet: %s\n", SDLNet_GetError());
    exit(1); //most of the time this is a major error, but do what you want.
}

See Also:
3.6.2 SDLNet_FreeSocketSet, 3.6.3 SDLNet_AddSocket, 4.5 SDLNet_SocketSet, 4.3 UDPsocket, 4.2 TCPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_FreeSocketSet

3.6.2 SDLNet_FreeSocketSet

void SDLNet_FreeSocketSet(SDLNet_SocketSet set)

set
The socket set to free from memory

Free the socket set from memory.
Do not reference the set after this call, except to allocate a new one.

Returns: nothing, this call always succeeds.

// free a socket set
//SDLNet_SocketSet set;

SDLNet_FreeSocketSet(set);
set=NULL; //this helps us remember that this set is not allocated

See Also:
3.6.1 SDLNet_AllocSocketSet, 3.6.3 SDLNet_AddSocket, 4.5 SDLNet_SocketSet, 4.3 UDPsocket, 4.2 TCPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_AddSocket

3.6.3 SDLNet_AddSocket

int SDLNet_AddSocket(SDLNet_SocketSet set, SDLNet_GenericSocket sock)
int SDLNet_TCP_AddSocket(SDLNet_SocketSet set, TCPsocket sock)
int SDLNet_UDP_AddSocket(SDLNet_SocketSet set, UDPsocket sock)

set
The socket set to add this socket to
sock
the socket to add to the socket set

Add a socket to a socket set that will be watched. TCP and UDP sockets should be added using the corrosponding macro (as in SDLNet_TCP_AddSocket for a TCP socket). The generic socket function will be called by the TCP and UDP macros. Both TCP and UDP sockets may be added to the same socket set. TCP clients and servers may all be in the same socket set. There is no limitation on the sockets in the socket set, other than they have been opened.

Returns: the number of sockets used in the set on success. -1 is returned on errors.

// add two sockets to a socket set
//SDLNet_SocketSet set;
//UDPsocket udpsock;
//TCPsocket tcpsock;
int numused;

numused=SDLNet_UDP_AddSocket(set,udpsock);
if(numused==-1) {
    printf("SDLNet_AddSocket: %s\n", SDLNet_GetError());
    // perhaps you need to restart the set and make it bigger...
}
numused=SDLNet_TCP_AddSocket(set,tcpsock);
if(numused==-1) {
    printf("SDLNet_AddSocket: %s\n", SDLNet_GetError());
    // perhaps you need to restart the set and make it bigger...
}

See Also:
3.6.1 SDLNet_AllocSocketSet, 3.6.4 SDLNet_DelSocket, 3.6.5 SDLNet_CheckSockets, 4.5 SDLNet_SocketSet, 4.3 UDPsocket, 4.2 TCPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_DelSocket

3.6.4 SDLNet_DelSocket

int SDLNet_DelSocket(SDLNet_SocketSet set, SDLNet_GenericSocket sock)
int SDLNet_TCP_DelSocket(SDLNet_SocketSet set, TCPsocket sock)
int SDLNet_UDP_DelSocket(SDLNet_SocketSet set, UDPsocket sock)

set
The socket set to remove this socket from
sock
the socket to remove from the socket set

Remove a socket from a socket set. Use this before closing a socket that you are watching with a socket set. This doesn't close the socket. Call the appropriate macro for TCP or UDP sockets. The generic socket function will be called by the TCP and UDP macros.

Returns: the number of sockets used in the set on success. -1 is returned on errors.

// remove two sockets from a socket set
//SDLNet_SocketSet set;
//UDPsocket udpsock;
//TCPsocket tcpsock;
int numused;

numused=SDLNet_UDP_DelSocket(set,udpsock);
if(numused==-1) {
    printf("SDLNet_DelSocket: %s\n", SDLNet_GetError());
    // perhaps the socket is not in the set
}
numused=SDLNet_TCP_DelSocket(set,tcpsock);
if(numused==-1) {
    printf("SDLNet_DelSocket: %s\n", SDLNet_GetError());
    // perhaps the socket is not in the set
}

See Also:
3.6.3 SDLNet_AddSocket, 3.6.2 SDLNet_FreeSocketSet, 4.5 SDLNet_SocketSet, 4.3 UDPsocket, 4.2 TCPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_CheckSockets

3.6.5 SDLNet_CheckSockets

int SDLNet_CheckSockets(SDLNet_SocketSet set, Uint32 timeout)

set
The socket set to check
timeout
The amount of time (in milliseconds).
0 means no waiting.
-1 means to wait over 49 days! (think about it)

Check all sockets in the socket set for activity. If a non-zero timeout is given then this function will wait for activity, or else it will wait for timeout milliseconds.

NOTE: "activity" also includes disconnections and other errors, which would be determined by a failed read/write attempt.

Returns: the number of sockets with activity. -1 is returned on errors, and you may not get a meaningful error message. -1 is also returned for an empty set (nothing to check).

// Wait for up to 1 second for network activity
//SDLNet_SocketSet set;
int numready;

numready=SDLNet_CheckSockets(set, 1000);
if(numready==-1) {
    printf("SDLNet_CheckSockets: %s\n", SDLNet_GetError());
    //most of the time this is a system error, where perror might help you.
    perror("SDLNet_CheckSockets");
}
else if(numready) {
    printf("There are %d sockets with activity!\n",numready);
    // check all sockets with SDLNet_SocketReady and handle the active ones.
}

See Also:
3.6.6 SDLNet_SocketReady, 3.6.3 SDLNet_AddSocket, 3.6.4 SDLNet_DelSocket, 3.6.1 SDLNet_AllocSocketSet, 4.5 SDLNet_SocketSet, 4.3 UDPsocket, 4.2 TCPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_SocketReady

3.6.6 SDLNet_SocketReady

int SDLNet_SocketReady(sock)

sock
The socket to check for activity.
Both UDPsocket and TCPsocket can be used with this function.

Check whether a socket has been marked as active. This function should only be used on a socket in a socket set, and that set has to have had SDLNet_CheckSockets (see section 3.6.5 SDLNet_CheckSockets) called upon it.

Returns: non-zero for activity. zero is returned for no activity.

// Wait forever for a connection attempt
//SDLNet_SocketSet set;
//TCPsocket serversock, client;
int numready;

numready=SDLNet_CheckSockets(set, 1000);
if(numready==-1) {
    printf("SDLNet_CheckSockets: %s\n", SDLNet_GetError());
    //most of the time this is a system error, where perror might help you.
    perror("SDLNet_CheckSockets");
}
else if(numready) {
    printf("There are %d sockets with activity!\n",numready);
    // check all sockets with SDLNet_SocketReady and handle the active ones.
    if(SDLNet_SocketReady(serversock)) {
        client=SDLNet_TCP_Accept(serversock);
        if(client) {
            // play with the client.
        }
    }
}

To just quickly do network handling with no waiting, we do this.

// Check for, and handle UDP data
//SDLNet_SocketSet set;
//UDPsocket udpsock;
//UDPpacket *packet;
int numready, numpkts;

numready=SDLNet_CheckSockets(set, 0);
if(numready==-1) {
    printf("SDLNet_CheckSockets: %s\n", SDLNet_GetError());
    //most of the time this is a system error, where perror might help you.
    perror("SDLNet_CheckSockets");
}
else if(numready) {
    printf("There are %d sockets with activity!\n",numready);
    // check all sockets with SDLNet_SocketReady and handle the active ones.
    if(SDLNet_SocketReady(udpsock)) {
        numpkts=SDLNet_UDP_Recv(udpsock,&packet);
        if(numpkts) {
            // process the packet.
        }
    }
}

See Also:
3.6.5 SDLNet_CheckSockets, 3.6.3 SDLNet_AddSocket, 3.6.4 SDLNet_DelSocket, 3.6.1 SDLNet_AllocSocketSet, 4.5 SDLNet_SocketSet, 4.3 UDPsocket, 4.2 TCPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: Types

4. Types

These types are defined and used by the SDL_net API.

4.1 IPaddress | IP Address and Port number
4.2 TCPsocket | TCP socket type (opaque)
4.3 UDPsocket | UDP socket type (opaque)
4.4 UDPpacket | UDP packet data encapsulation
4.5 SDLNet_SocketSet | Socket Set type (opaque)
4.6 SDLNet_GenericSocket | A generic type for UDP and TCP sockets

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: IPaddress

4.1 IPaddress

typedef struct {
    Uint32 host;            /* 32-bit IPv4 host address */
    Uint16 port;            /* 16-bit protocol port */
} IPaddress;

host
the IPv4 address of a host, encoded in Network Byte Order.
port
the IPv4 port number of a socket, encoded in Network Byte Order.

This type contains the information used to form network connections and sockets.

See Also:
3.2 Name Resolution, 3.3.1 SDLNet_TCP_Open, 4.4 UDPpacket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: TCPsocket

4.2 TCPsocket

typedef struct _TCPsocket *TCPsocket;

This is an opaque data type used for TCP connections. This is a pointer, and so it could be NULL at times. NULL would indicate no socket has been established.

See Also:
3.3 TCP Sockets, 4.3 UDPsocket, 4.6 SDLNet_GenericSocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: UDPsocket

4.3 UDPsocket

typedef struct _UDPsocket *UDPsocket;

This is an opaque data type used for UDP sockets. This is a pointer, and so it could be NULL at times. NULL would indicate no socket has been established.

See Also:
3.4 UDP Sockets, 4.4 UDPpacket, 4.2 TCPsocket, 4.6 SDLNet_GenericSocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: UDPpacket

4.4 UDPpacket

typedef struct {
    int channel;          /* The src/dst channel of the packet */
    Uint8 *data;          /* The packet data */
    int len;              /* The length of the packet data */
    int maxlen;           /* The size of the data buffer */
    int status;           /* packet status after sending */
    IPaddress address;    /* The source/dest address of an
                                   incoming/outgoing packet */
} UDPpacket;

channel
The (software) channel number for this packet. This can also be used as a priority value for the packet. If no channel is assigned, the value is -1.
data
The data contained in this packet, this is the meat.
len
This is the meaningful length of the data in bytes.
maxlen
This is size of the data buffer, which may be larger than the meaningful length. This is only used for packet creation on the senders side.
status
This contains the number of bytes sent, or a -1 on errors, after sending. This is useless for a received packet.
address
This is the resolved IPaddress to be used when sending, or it is the remote source of a received packet.

This struct is used with UDPsockets to send and receive data. It also helps keep track of a packets sending/receiving settings and status. The channels concept helps prioritize, or segregate differring types of data packets.

See Also:
3.5 UDP Packets, 4.3 UDPsocket, 4.1 IPaddress

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_SocketSet

4.5 SDLNet_SocketSet

typedef struct _SDLNet_SocketSet *SDLNet_SocketSet;

This is an opaque data type used for socket sets. This is a pointer, and so it could be NULL at times. NULL would indicate no socket set has been created.

See Also:
3.6 Socket Sets, 4.2 TCPsocket, 4.3 UDPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: SDLNet_GenericSocket

4.6 SDLNet_GenericSocket

typedef struct {
    int ready;
} *SDLNet_GenericSocket;

ready
non-zero when data is ready to be read, or a server socket has a connection attempt ready to be accepted.

This data type is able to be used for both UDPsocket and TCPsocket types.
After calling SDLNet_CheckSockets, if this socket is in SDLNet_SocketSet used, the ready will be set according to activity on the socket. This is the only real use for this type, as it doesn't help you know what type of socket it is.

See Also:
3.6 Socket Sets, 4.2 TCPsocket, 4.3 UDPsocket

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: Defines

5. Defines

SDL_NET_MAJOR_VERSION
1
SDL_net library major number at compilation time
SDL_NET_MINOR_VERSION
2
SDL_net library minor number at compilation time
SDL_NET_PATCHLEVEL
7
SDL_net library patch level at compilation time
INADDR_ANY
0x00000000 (0.0.0.0)
used for listening on all network interfaces.
INADDR_NONE
0xFFFFFFFF (255.255.255.255)
which has limited applications.
INADDR_BROADCAST
0xFFFFFFFF (255.255.255.255)
used as destination when sending a message to all clients on a subnet that allows broadcasts.
SDLNET_MAX_UDPCHANNELS
32
The maximum number of channels on a UDP socket.
SDLNET_MAX_UDPADDRESSES
4
The maximum number of addresses bound to a single UDP socket channel

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: Glossary

6. Glossary

Network Byte Order
Also known as Big-Endian. Which means the most significant byte comes first in storage. Sparc and Motorola 68k based chips are MSB ordered.
(SDL defines this as SDL_BYTEORDER==SDL_BIG_ENDIAN)

Little-Endian(LSB) is stored in the opposite order, with the least significant byte first in memory. Intel and AMD are two LSB machines.
(SDL defines this as SDL_BYTEORDER==SDL_LIL_ENDIAN)

For network addresses, 1.2.3.4 is always stored as {0x01 0x02 0x03 0x04}.

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: Index

Index

Jump to: B I L M N R S T U

 | Index Entry | Section
B |  |
 | Big-Endian | 6. Glossary
I |  |
 | INADDR_ANY | 5. Defines
 | INADDR_BROADCAST | 5. Defines
 | INADDR_NONE | 5. Defines
 | IPaddress | 4.1 IPaddress
L |  |
 | Little-Endian | 6. Glossary
 | LSB | 6. Glossary
M |  |
 | MSB | 6. Glossary
N |  |
 | Network Byte Order | 6. Glossary
R |  |
 | README | 1. Overview
S |  |
 | sdl-config | 2.2 Compiling
 | SDL_NET_MAJOR_VERSION | 5. Defines
 | SDL_NET_MINOR_VERSION | 5. Defines
 | SDL_NET_PATCHLEVEL | 5. Defines
 | SDL_NET_VERSION | 3.1.1 SDLNet_Linked_Version
 | SDLNet_AddSocket | 3.6.3 SDLNet_AddSocket
 | SDLNet_AllocPacket | 3.5.1 SDLNet_AllocPacket
 | SDLNet_AllocPacketV | 3.5.4 SDLNet_AllocPacketV
 | SDLNet_AllocSocketSet | 3.6.1 SDLNet_AllocSocketSet
 | SDLNet_CheckSockets | 3.6.5 SDLNet_CheckSockets
 | SDLNet_DelSocket | 3.6.4 SDLNet_DelSocket
 | SDLNet_FreePacket | 3.5.3 SDLNet_FreePacket
 | SDLNet_FreePacketV | 3.5.5 SDLNet_FreePacketV
 | SDLNet_FreeSocketSet | 3.6.2 SDLNet_FreeSocketSet
 | SDLNet_GenericSocket | 4.6 SDLNet_GenericSocket
 | SDLNet_GetError | 3.1.4 SDLNet_GetError
 | SDLNet_Init | 3.1.2 SDLNet_Init
 | SDLNet_Linked_Version | 3.1.1 SDLNet_Linked_Version
 | SDLNET_MAX_UDPADDRESSES | 5. Defines
 | SDLNET_MAX_UDPCHANNELS | 5. Defines
 | SDLNet_Quit | 3.1.3 SDLNet_Quit
 | SDLNet_Read16 | 3.1.7 SDLNet_Read16
 | SDLNet_Read32 | 3.1.8 SDLNet_Read32
 | SDLNet_ResizePacket | 3.5.2 SDLNet_ResizePacket
 | SDLNet_ResolveHost | 3.2.1 SDLNet_ResolveHost
 | SDLNet_ResolveIP | 3.2.2 SDLNet_ResolveIP
 | SDLNet_SocketReady | 3.6.6 SDLNet_SocketReady
 | SDLNet_SocketSet | 4.5 SDLNet_SocketSet
 | SDLNet_TCP_Accept | 3.3.3 SDLNet_TCP_Accept
 | SDLNet_TCP_AddSocket | 3.6.3 SDLNet_AddSocket
 | SDLNet_TCP_Close | 3.3.2 SDLNet_TCP_Close
 | SDLNet_TCP_DelSocket | 3.6.4 SDLNet_DelSocket
 | SDLNet_TCP_GetPeerAddress | 3.3.4 SDLNet_TCP_GetPeerAddress
 | SDLNet_TCP_Open | 3.3.1 SDLNet_TCP_Open
 | SDLNet_TCP_Recv | 3.3.6 SDLNet_TCP_Recv
 | SDLNet_TCP_Send | 3.3.5 SDLNet_TCP_Send
 | SDLNet_UDP_AddSocket | 3.6.3 SDLNet_AddSocket
 | SDLNet_UDP_Bind | 3.4.3 SDLNet_UDP_Bind
 | SDLNet_UDP_Close | 3.4.2 SDLNet_UDP_Close
 | SDLNet_UDP_DelSocket | 3.6.4 SDLNet_DelSocket
 | SDLNet_UDP_GetPeerAddress | 3.4.5 SDLNet_UDP_GetPeerAddress
 | SDLNet_UDP_Open | 3.4.1 SDLNet_UDP_Open
 | SDLNet_UDP_Recv | 3.4.7 SDLNet_UDP_Recv
 | SDLNet_UDP_RecvV | 3.4.9 SDLNet_UDP_RecvV
 | SDLNet_UDP_Send | 3.4.6 SDLNet_UDP_Send
 | SDLNet_UDP_SendV | 3.4.8 SDLNet_UDP_SendV
 | SDLNet_UDP_Unbind | 3.4.4 SDLNet_UDP_Unbind
 | SDLNet_Write16 | 3.1.5 SDLNet_Write16
 | SDLNet_Write32 | 3.1.6 SDLNet_Write32
T |  |
 | TCPsocket | 4.2 TCPsocket
U |  |
 | UDPpacket | 4.4 UDPpacket
 | UDPsocket | 4.3 UDPsocket

Jump to: B I L M N R S T U

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: About this document

About this document

This document was generated on November, 3 2009 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7: Short Table of Contents

Short Table of Contents

1. Overview
2. Getting Started
3. Functions
4. Types
5. Defines
6. Glossary
Index

This document was generated on November, 3 2009 using texi2html


SDL_net 1.2.7:

Content

1. Overview
2. Getting Started
3. Functions
4. Types
5. Defines
6. Glossary
Index


SDL_ttf 2.0.10: SDL_ttf 2.0.10

SDL_ttf 2.0.10

1. Overview The README from the SDL_ttf distribution

2. Getting Started Using SDL_ttf

3. Functions | Functions supported by the SDL_ttf API
4. Types | Types used with the SDL_ttf API
5. Defines | Defined values/macros in the SDL_ttf API

6. Glossary Terms used in this document

Index Index of selected words

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: Overview

1. Overview

A Little Bit About Me

I am currently, as I write this document, a programmer for Raytheon. There I do all sorts of communications, network, GUI, and other general programming tasks in C/C++ on the Solaris and sometimes Linux Operating Systems. I've used SDL_ttf as one of the many methods of putting text on my SDL applications, and use it in my own SDL GUI code as well. While this document doesn't explain how and where to get fonts to use, it will explain how to use them with SDL_ttf.

Feel free to contact me: JonathanCAtkins@gmail.com

The latest version of this library is available from:
SDL_ttf Homepage

I am also usually on IRC at irc.freenode.net in the #SDL channel as LIM

This is the README in the SDL_ttf source archive.

This library is a wrapper around the excellent FreeType 1.2 library, available at: Freetype Homepage

WARNING: There may be patent issues with using the FreeType library. Check the FreeType website for up-to-date details.

This library allows you to use TrueType fonts to render text in SDL applications.

To make the library, first install the FreeType library, then type 'make' to build the SDL truetype library and 'make all' to build the demo application.

Be careful when including fonts with your application, as many of them are copyrighted. The Microsoft fonts, for example, are not freely redistributable and even the free "web" fonts they provide are only redistributable in their special executable installer form (May 1998). There are plenty of freeware and shareware fonts available on the Internet though, which may suit your purposes.

Please see the file "COPYING" for license information for this library.

Enjoy! -Sam Lantinga slouken@devolution.com (5/1/98)

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: Getting Started

2. Getting Started

This assumes you have gotten SDL_ttf and installed it on your system. SDL_ttf has an INSTALL document in the source distribution to help you get it compiled and installed.

Generally, installation consists of:

./configure
make
make install

SDL_ttf supports loading fonts from TrueType font files, normally ending in .ttf, though some .fon files are also valid for use. Note that most fonts are copyrighted, check the license on the font before you use and redistribute it.

Some free font sources are:

  • Free UCS Outline Fonts
  • Fonthead Design
  • Bitstream Vera Fonts
  • FreeUniFont
  • 1001 Fonts
  • Google!

You may also want to look at some demonstration code which may be downloaded from:
http://www.jonatkins.org/SDL_ttf/

2.1 Includes | The include files to use for SDL_ttf
2.2 Compiling | Using the SDL_ttf library and header file.

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: Includes

2.1 Includes

To use SDL_ttf functions in a C/C++ source code file, you must use the SDL_ttf.h include file:

#include "SDL_ttf.h"

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: Compiling

2.2 Compiling

To link with SDL_ttf you should use sdl-config to get the required SDL compilation options. After that, compiling with SDL_ttf is quite easy.
Note: Some systems may not have the SDL_ttf library and include file in the same place as the SDL library and includes are located, in that case you will need to add more -I and -L paths to these command lines. All examples are gcc and perhaps UNIX specific, but adaptable to many compilers and Operating Systems.

Simple Example for compiling to an object file:

gcc -c `sdl-config --cflags` mysource.c

Simple Example for linking an executable (Unix style has no .exe):

gcc -o myprogram mysource.o `sdl-config --libs` -lSDL_ttf

Now myprogram is ready to run.

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: Functions

3. Functions

These are the functions in the SDL_ttf API.

3.1 General | API activation, info, and error handling
3.2 Management | Loading fonts from files or memory
3.3 Attributes | Getting and Setting font attributes
3.4 Render | Drawing strings and glyphs with a font

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: General

3.1 General

These functions are core elements in SDL_ttf.

Info
3.1.1 TTF_Linked_Version Get runtime version number
Activation
3.1.2 TTF_Init | Initialize API
3.1.3 TTF_WasInit | Query API initialization status
3.1.4 TTF_Quit | Cleanup API
Errors
3.1.5 TTF_SetError | Set the current error string
3.1.6 TTF_GetError | Get the current error string

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_Linked_Version

3.1.1 TTF_Linked_Version

const SDL_version *TTF_Linked_Version()
void SDL_TTF_VERSION(SDL_version *compile_version)

This works similar to SDL_Linked_Version and SDL_VERSION.
Using these you can compare the runtime version to the version that you compiled with.
No prior initialization needs to be done before these function/macros are used.

SDL_version compile_version;
const SDL_version *link_version=TTF_Linked_Version();
SDL_TTF_VERSION(&compile_version);
printf("compiled with SDL_ttf version: %d.%d.%d\n",
        compile_version.major,
        compile_version.minor,
        compile_version.patch);
printf("running with SDL_ttf version: %d.%d.%d\n",
        link_version->major,
        link_version->minor,
        link_version->patch);

See Also:
3.1.2 TTF_Init

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_Init

3.1.2 TTF_Init

int TTF_Init()

Initialize the truetype font API.
This must be called before using other functions in this library, except TTF_WasInit.
SDL does not have to be initialized before this call.

Returns: 0 on success, -1 on any error

if(TTF_Init()==-1) {
    printf("TTF_Init: %s\n", TTF_GetError());
    exit(2);
}

See Also:
3.1.4 TTF_Quit, 3.1.3 TTF_WasInit

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_WasInit

3.1.3 TTF_WasInit

int TTF_WasInit()

Query the initilization status of the truetype font API.
You may, of course, use this before TTF_Init to avoid initializing twice in a row. Or use this to determine if you need to call TTF_Quit.

Returns: 1 if already initialized, 0 if not initialized.

if(!TTF_WasInit() && TTF_Init()==-1) {
    printf("TTF_Init: %s\n", TTF_GetError());
    exit(1);
}

See Also:
3.1.2 TTF_Init, 3.1.4 TTF_Quit

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_Quit

3.1.4 TTF_Quit

void TTF_Quit()

Shutdown and cleanup the truetype font API.
After calling this the SDL_ttf functions should not be used, excepting TTF_WasInit. You may, of course, use TTF_Init to use the functionality again.

TTF_Quit();
// you could SDL_Quit(); here...or not.

See Also:
3.1.2 TTF_Init, 3.1.3 TTF_WasInit

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_SetError

3.1.5 TTF_SetError

void TTF_SetError(const char *fmt, ...)

This is really a defined macro for SDL_SetError, which sets the error string which may be fetched with TTF_GetError (or SDL_GetError). This functions acts like printf, except that it is limited to SDL_ERRBUFIZE(1024) chars in length. It only accepts the following format types: %s, %d, %f, %p. No flags, precisions, field widths, nor length modifiers, are supported in the format. For any more specifics read the SDL docs.

int myfunc(int i) {
    TTF_SetError("myfunc is not implemented! %d was passed in.",i);
    return(-1);
}

See Also:
3.1.6 TTF_GetError

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_GetError

3.1.6 TTF_GetError

char *TTF_GetError()

This is really a defined macro for SDL_GetError. It returns the last error set by TTF_SetError (or SDL_SetError) as a string. Use this to tell the user what happened when an error status has been returned from an SDL_ttf function call.

Returns: a char pointer (string) containing a human readable version or the reason for the last error that occured.

printf("Oh My Goodness, an error : %s", TTF_GetError());

See Also:
3.1.5 TTF_SetError

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: Management

3.2 Management

These functions deal with loading and freeing a TTF_Font.

Loading
3.2.1 TTF_OpenFont | From a file
3.2.2 TTF_OpenFontRW | Using RWops
3.2.3 TTF_OpenFontIndex | From a file, with an index
3.2.4 TTF_OpenFontIndexRW | From memory, with an index
Freeing
3.2.5 TTF_CloseFont Free a loaded font

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_OpenFont

3.2.1 TTF_OpenFont

TTF_Font *TTF_OpenFont(const char *file, int ptsize)

file
File name to load font from.
ptsize
Point size (based on 72DPI) to load font as. This basically translates to pixel height.

Load file for use as a font, at ptsize size. This is actually TTF_OpenFontIndex(file, ptsize, 0). This can load TTF and FON files.

Returns: a pointer to the font as a TTF_Font. NULL is returned on errors.

// load font.ttf at size 16 into font
TTF_Font *font;
font=TTF_OpenFont("font.ttf", 16);
if(!font) {
    printf("TTF_OpenFont: %s\n", TTF_GetError());
    // handle error
}

See Also:
3.2.3 TTF_OpenFontIndex, 3.2.2 TTF_OpenFontRW, 3.2.5 TTF_CloseFont

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_OpenFontRW

3.2.2 TTF_OpenFontRW

TTF_Font *TTF_OpenFontRW(SDL_RWops *src, int freesrc, int ptsize)

src
The source SDL_RWops as a pointer. The font is loaded from this.
freesrc
A non-zero value means it will automatically close and free the src for you after it finishes using the src, even if a noncritical error occured.
ptsize
Point size (based on 72DPI) to load font as. This basically translates to pixel height.

Load src for use as a font, at ptsize size. This is actually TTF_OpenFontIndexRW(src, freesrc, ptsize, 0) This can load TTF and FON formats. Using SDL_RWops is not covered here, but they enable you to load from almost any source.

NOTE: src is not checked for NULL, so be careful.

Returns: a pointer to the font as a TTF_Font. NULL is returned on errors.

// load font.ttf at size 16 into font
TTF_Font *font;
font=TTF_OpenFontRW(SDL_RWFromFile("font.ttf"), 1, 16);
if(!font) {
    printf("TTF_OpenFontRW: %s\n", TTF_GetError());
    // handle error
}
Note that this is unsafe because we don't check the validity of the SDL_RWFromFile's returned pointer.

See Also:
3.2.4 TTF_OpenFontIndexRW, 3.2.1 TTF_OpenFont, 3.2.5 TTF_CloseFont

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_OpenFontIndex

3.2.3 TTF_OpenFontIndex

TTF_Font *TTF_OpenFontIndex(const char *file, int ptsize, long index)

file
File name to load font from.
ptsize
Point size (based on 72DPI) to load font as. This basically translates to pixel height.
index
choose a font face from a file containing multiple font faces. The first face is always index 0.

Load file, face index, for use as a font, at ptsize size. This is actually TTF_OpenFontIndexRW(SDL_RWFromFile(file), ptsize, index), but checks that the RWops it creates is not NULL. This can load TTF and FON files.

Returns: a pointer to the font as a TTF_Font. NULL is returned on errors.

// load font.ttf, face 0, at size 16 into font
TTF_Font *font;
font=TTF_OpenFontIndex("font.ttf", 16, 0);
if(!font) {
    printf("TTF_OpenFontIndex: %s\n", TTF_GetError());
    // handle error
}

See Also:
3.2.4 TTF_OpenFontIndexRW, 3.2.1 TTF_OpenFont, 3.2.5 TTF_CloseFont

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_OpenFontIndexRW

3.2.4 TTF_OpenFontIndexRW

TTF_Font *TTF_OpenFontIndexRW(SDL_RWops *src, int freesrc, int ptsize, long index)

src
The source SDL_RWops as a pointer. The font is loaded from this.
freesrc
A non-zero value means it will automatically close and free the src for you after it finishes using the src, even if a noncritical error occured.
ptsize
Point size (based on 72DPI) to load font as. This basically translates to pixel height.
index
Choose a font face from a file containing multiple font faces. The first face is always index 0.

Load src, face index, for use as a font, at ptsize size. This can load TTF and FON formats.
Using SDL_RWops is not covered here, but they enable you to load from almost any source.

NOTE: src is not checked for NULL, so be careful.

Returns: a pointer to the font as a TTF_Font. NULL is returned on errors.

// load font.ttf, face 0, at size 16 into font
TTF_Font *font;
font=TTF_OpenFontRW(SDL_RWFromFile("font.ttf"), 1, 16, 0);
if(!font) {
    printf("TTF_OpenFontIndexRW: %s\n", TTF_GetError());
    // handle error
}
Note that this is unsafe because we don't check the validity of the SDL_RWFromFile's returned pointer.

See Also:
3.2.3 TTF_OpenFontIndex, 3.2.2 TTF_OpenFontRW, 3.2.5 TTF_CloseFont

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_CloseFont

3.2.5 TTF_CloseFont

void TTF_CloseFont(TTF_Font *font)

font
Pointer to the TTF_Font to free.

Free the memory used by font, and free font itself as well. Do not use font after this without loading a new font to it.

// free the font
// TTF_Font *font;
TTF_CloseFont(font);
font=NULL; // to be safe...

See Also:
3.2.1 TTF_OpenFont, 3.2.2 TTF_OpenFontRW, 3.2.3 TTF_OpenFontIndex, 3.2.4 TTF_OpenFontIndexRW

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: Attributes

3.3 Attributes

These functions deal with TTF_Font, and global, attributes.

See the end of 3.3.19 TTF_GlyphMetrics for info on how the metrics work.

Global Attributes
3.3.1 TTF_ByteSwappedUNICODE Set default UNICODE byte swapping mode
Font Style
3.3.2 TTF_GetFontStyle | Get font render style
3.3.3 TTF_SetFontStyle | Set font render style
3.3.4 TTF_GetFontOutline | Get font outline width
3.3.5 TTF_SetFontOutline | Set font outline width
Font Settings
3.3.6 TTF_GetFontHinting | Get freetype hinter setting
3.3.7 TTF_SetFontHinting | Set freetype hinter setting
3.3.8 TTF_GetFontKerning | Get freetype kerning setting
3.3.9 TTF_SetFontKerning | Set freetype kerning setting
Font Metrics
3.3.10 TTF_FontHeight | Get font maximum total height
3.3.11 TTF_FontAscent | Get font highest ascent (height above base)
3.3.12 TTF_FontDescent | Get font lowest descent (height below base)
3.3.13 TTF_FontLineSkip | Get font recommended line spacing
Face Attributes
3.3.14 TTF_FontFaces | Get the number of faces in a font
3.3.15 TTF_FontFaceIsFixedWidth | Get whether font is monospaced or not
3.3.16 TTF_FontFaceFamilyName | Get current font face family name string
3.3.17 TTF_FontFaceStyleName | Get current font face style name string
Glyphs
3.3.18 TTF_GlyphIsProvided | Get individual font glyph availability
3.3.19 TTF_GlyphMetrics | Get individual font glyph metrics
Text Metrics
3.3.20 TTF_SizeText | Get size of LATIN1 text string as would be rendered
3.3.21 TTF_SizeUTF8 | Get size of UTF8 text string as would be rendered
3.3.22 TTF_SizeUNICODE | Get size of UNICODE text string as would be rendered

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_ByteSwappedUNICODE

3.3.1 TTF_ByteSwappedUNICODE

void TTF_ByteSwappedUNICODE(int swapped)

swapped
if non-zero then UNICODE data is byte swapped relative to the CPU's native endianness.
if zero, then do not swap UNICODE data, use the CPU's native endianness.

This function tells SDL_ttf whether UNICODE (Uint16 per character) text is generally byteswapped. A UNICODE_BOM_NATIVE or UNICODE_BOM_SWAPPED character in a string will temporarily override this setting for the remainder of that string, however this setting will be restored for the next one. The default mode is non-swapped, native endianness of the CPU.

// Turn on byte swapping for UNICODE text
TTF_ByteSwappedUNICODE(1);

See Also:
5. Defines

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_GetFontStyle

3.3.2 TTF_GetFontStyle

int TTF_GetFontStyle(TTF_Font *font)

font
The loaded font to get the style of.

Get the rendering style of the loaded font.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The style as a bitmask composed of the following masks:
TTF_STYLE_BOLD
TTF_STYLE_ITALIC
TTF_STYLE_UNDERLINE
TTF_STYLE_STRIKETHROUGH
If no style is set then TTF_STYLE_NORMAL is returned.

// get the loaded font's style
//TTF_Font *font;
int style;
style=TTF_GetFontStyle(font);
printf("The font style is:");
if(style==TTF_STYLE_NORMAL)
    printf(" normal");
else {
    if(style&TTF_STYLE_BOLD)
        printf(" bold");
    if(style&TTF_STYLE_ITALIC)
        printf(" italic");
    if(style&TTF_STYLE_UNDERLINE)
        printf(" underline");
    if(style&TTF_STYLE_STRIKETHROUGH)
        printf(" strikethrough");
}
printf("\n");

See Also:
3.3.3 TTF_SetFontStyle,
5. Defines

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_SetFontStyle

3.3.3 TTF_SetFontStyle

void TTF_SetFontStyle(TTF_Font *font, int style)

font
The loaded font to set the style of.
style
The style as a bitmask composed of the following masks:
TTF_STYLE_BOLD
TTF_STYLE_ITALIC
TTF_STYLE_UNDERLINE
TTF_STYLE_STRIKETHROUGH
If no style is desired then use TTF_STYLE_NORMAL, which is the default.

Set the rendering style of the loaded font.

NOTE: Passing a NULL font into this function will cause a segfault.

NOTE: This will flush the internal cache of previously rendered glyphs, even if there is no change in style, so it may be best to check the current style using TTF_GetFontStyle first.

NOTE: TTF_STYLE_UNDERLINE may cause surfaces created by TTF_RenderGlyph_* functions to be extended vertically, downward only, to encompass the underline if the original glyph metrics didn't allow for the underline to be drawn below. This does not change the math used to place a glyph using glyph metrics.
On the other hand TTF_STYLE_STRIKETHROUGH doesn't extend the glyph, since this would invalidate the metrics used to position the glyph when blitting, because they would likely be extended vertically upward. There is perhaps a workaround, but it would require programs to be smarter about glyph blitting math than they are currently designed for.
Still, sometimes the underline or strikethrough may be outside of the generated surface, and thus not visible when blitted to the screen. In this case, you should probably turn off these styles and draw your own strikethroughs and underlines.

// set the loaded font's style to bold italics
//TTF_Font *font;
TTF_SetFontStyle(font, TTF_STYLE_BOLD|TTF_STYLE_ITALIC);

// render some text in bold italics...

// set the loaded font's style back to normal
TTF_SetFontStyle(font, TTF_STYLE_NORMAL);

See Also:
3.3.2 TTF_GetFontStyle,
5. Defines

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_GetFontOutline

3.3.4 TTF_GetFontOutline

int TTF_GetFontOutline(TTF_Font *font)

font
The loaded font to get the outline size of.

Get the current outline size of the loaded font.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The size of the outline currently set on the font, in pixels.

// get the loaded font's outline width
//TTF_Font *font;
int outline=TTF_GetFontOutline(font);
printf("The font outline width is %d pixels\n",outline);

See Also:
3.3.5 TTF_SetFontOutline,
3.3.2 TTF_GetFontStyle

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_SetFontOutline

3.3.5 TTF_SetFontOutline

void TTF_SetFontOutline(TTF_Font *font, int outline)

font
The loaded font to set the outline size of.
outline
The size of outline desired, in pixels.
Use 0(zero) to turn off outlining.

Set the outline pixel width of the loaded font.

NOTE: Passing a NULL font into this function will cause a segfault.

NOTE: This will flush the internal cache of previously rendered glyphs, even if there is no change in outline size, so it may be best to check the current outline size using TTF_GetFontOutline first.

// set the loaded font's outline to 1 pixel wide
//TTF_Font *font;
TTF_SetFontOutline(font, 1);

// render some outlined text...

// set the loaded font's outline back to normal
TTF_SetFontOutline(font, 0);

See Also:
3.3.4 TTF_GetFontOutline,
3.3.3 TTF_SetFontStyle

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_GetFontHinting

3.3.6 TTF_GetFontHinting

int TTF_GetFontHinting(TTF_Font *font)

font
The loaded font to get the hinting setting of.

Get the current hinting setting of the loaded font.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The hinting type matching one of the following defined values:
TTF_HINTING_NORMAL
TTF_HINTING_LIGHT
TTF_HINTING_MONO
TTF_HINTING_NONE
If no hinting is set then TTF_HINTING_NORMAL is returned.

// get the loaded font's hinting setting
//TTF_Font *font;
int hinting=TTF_GetFontHinting(font);
printf("The font hinting is currently set to %s\n",
        hinting==0?"Normal":
        hinting==1?"Light":
        hinting==2?"Mono":
        hinting==3?"None":
        "Unknonwn");

See Also:
3.3.7 TTF_SetFontHinting,
5. Defines,
see section Hinting,
Font Hinting @ Wikipedia,
FreeType Hinting and Bitmap rendering,
FreeType Hinting Modes

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_SetFontHinting

3.3.7 TTF_SetFontHinting

void TTF_SetFontHinting(TTF_Font *font, int hinting)

font
The loaded font to set the outline size of.
hinting
The hinting setting desired, which is one of:
TTF_HINTING_NORMAL
TTF_HINTING_LIGHT
TTF_HINTING_MONO
TTF_HINTING_NONE
The default is TTF_HINTING_NORMAL.

Set the hinting of the loaded font. You should experiment with this setting if you know which font you are using beforehand, especially when using smaller sized fonts. If the user is selecting a font, you may wish to let them select the hinting mode for that font as well.

NOTE: Passing a NULL font into this function will cause a segfault.

NOTE: This will flush the internal cache of previously rendered glyphs, even if there is no change in hinting, so it may be best to check the current hinting by using TTF_GetFontHinting first.

// set the loaded font's hinting to optimized for monochrome rendering
//TTF_Font *font;
TTF_SetFontHinting(font, TTF_HINTING_MONO);

// render some monochrome text...

// set the loaded font's hinting back to normal
TTF_SetFontHinting(font, TTF_HINTING_NORMAL);

See Also:
3.3.6 TTF_GetFontHinting,
5. Defines,
see section Hinting,
Font Hinting @ Wikipedia,
FreeType Hinting and Bitmap rendering,
FreeType Hinting Modes

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_GetFontKerning

3.3.8 TTF_GetFontKerning

int TTF_GetFontKerning(TTF_Font *font)

font
The loaded font to get the kerning setting of.

Get the current kerning setting of the loaded font.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: 0(zero) if kerning is disabled. A non-zero value is returned when enabled. The default for a newly loaded font is enabled(1).

// get the loaded font's kerning setting
//TTF_Font *font;
int kerning=TTF_GetFontKerning(font);
printf("The font kerning is currently set to %s\n",
        kerning==0?"Off":"On");

See Also:
3.3.9 TTF_SetFontKerning,
see section Kerning,
Kerning @ Wikipedia

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_SetFontKerning

3.3.9 TTF_SetFontKerning

void TTF_SetFontKerning(TTF_Font *font, int allowed)

font
The loaded font to set the outline size of.
allowed
0 to diable kerning.
non-zero to enable kerning. The default is 1, enabled.

Set whther to use kerning when rendering the loaded font. This has no effect on individual glyphs, but rather when rendering whole strings of characters, at least a word at a time. Perhaps the only time to disable this is when kerning is not working for a specific font, resulting in overlapping glyphs or abnormal spacing within words.

NOTE: Passing a NULL font into this function will cause a segfault.

// turn off kerning on the loaded font
//TTF_Font *font;
TTF_SetFontKerning(font, 0);

// render some text string...

// turn kerning back on for the loaded font
TTF_SetFontKerning(font, 1);

See Also:
3.3.8 TTF_GetFontKerning,
see section Kerning,
Kerning @ Wikipedia

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_FontHeight

3.3.10 TTF_FontHeight

int TTF_FontHeight(const TTF_Font *font)

font
The loaded font to get the max height of.

Get the maximum pixel height of all glyphs of the loaded font. You may use this height for rendering text as close together vertically as possible, though adding at least one pixel height to it will space it so they can't touch. Remember that SDL_ttf doesn't handle multiline printing, so you are responsible for line spacing, see the TTF_FontLineSkip as well.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The maximum pixel height of all glyphs in the font.

// get the loaded font's max height
//TTF_Font *font;
printf("The font max height is: %d\n", TTF_FontHeight(font));

See Also:
3.3.11 TTF_FontAscent,
3.3.12 TTF_FontDescent,
3.3.13 TTF_FontLineSkip,
3.3.19 TTF_GlyphMetrics

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_FontAscent

3.3.11 TTF_FontAscent

int TTF_FontAscent(const TTF_Font *font)

font
The loaded font to get the ascent (height above baseline) of.

Get the maximum pixel ascent of all glyphs of the loaded font. This can also be interpreted as the distance from the top of the font to the baseline.
It could be used when drawing an individual glyph relative to a top point, by combining it with the glyph's maxy metric to resolve the top of the rectangle used when blitting the glyph on the screen.

rect.y = top + TTF_FontAscent(font) - glyph_metric.maxy;

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The maximum pixel ascent of all glyphs in the font.

// get the loaded font's max ascent
//TTF_Font *font;

printf("The font ascent is: %d\n", TTF_FontAscent(font));

See Also:
3.3.10 TTF_FontHeight,
3.3.12 TTF_FontDescent,
3.3.13 TTF_FontLineSkip,
3.3.19 TTF_GlyphMetrics

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_FontDescent

3.3.12 TTF_FontDescent

int TTF_FontDescent(const TTF_Font *font)

font
The loaded font to get the descent (height below baseline) of.

Get the maximum pixel descent of all glyphs of the loaded font. This can also be interpreted as the distance from the baseline to the bottom of the font.
It could be used when drawing an individual glyph relative to a bottom point, by combining it with the glyph's maxy metric to resolve the top of the rectangle used when blitting the glyph on the screen.

rect.y = bottom - TTF_FontDescent(font) - glyph_metric.maxy;

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The maximum pixel height of all glyphs in the font.

// get the loaded font's max descent
//TTF_Font *font;

printf("The font descent is: %d\n", TTF_FontDescent(font));

See Also:
3.3.10 TTF_FontHeight,
3.3.11 TTF_FontAscent,
3.3.13 TTF_FontLineSkip,
3.3.19 TTF_GlyphMetrics

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_FontLineSkip

3.3.13 TTF_FontLineSkip

int TTF_FontLineSkip(const TTF_Font *font)

font
The loaded font to get the line skip height of.

Get the recommended pixel height of a rendered line of text of the loaded font. This is usually larger than the TTF_FontHeight of the font.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The maximum pixel height of all glyphs in the font.

// get the loaded font's line skip height
//TTF_Font *font;

printf("The font line skip is: %d\n", TTF_FontLineSkip(font));

See Also:
3.3.10 TTF_FontHeight,
3.3.11 TTF_FontAscent,
3.3.12 TTF_FontDescent,
3.3.19 TTF_GlyphMetrics

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_FontFaces

3.3.14 TTF_FontFaces

long TTF_FontFaces(const TTF_Font *font)

font
The loaded font to get the number of available faces from.

Get the number of faces ("sub-fonts") available in the loaded font. This is a count of the number of specific fonts (based on size and style and other typographical features perhaps) contained in the font itself. It seems to be a useless fact to know, since it can't be applied in any other SDL_ttf functions.
NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The number of faces in the font.

// get the loaded font's number of faces
//TTF_Font *font;

printf("The number of faces in the font is: %ld\n", TTF_FontFaces(font));

See Also:
3.3.15 TTF_FontFaceIsFixedWidth,
3.3.16 TTF_FontFaceFamilyName,
3.3.17 TTF_FontFaceStyleName

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_FontFaceIsFixedWidth

3.3.15 TTF_FontFaceIsFixedWidth

int TTF_FontFaceIsFixedWidth(const TTF_Font *font)

font
The loaded font to get the fixed width status of.

Test if the current font face of the loaded font is a fixed width font. Fixed width fonts are monospace, meaning every character that exists in the font is the same width, thus you can assume that a rendered string's width is going to be the result of a simple calculation:
glyph_width * string_length
NOTE: Passing a NULL font into this function will cause a segfault.

Returns: >0 if font is a fixed width font. 0 if not a fixed width font.

// get the loaded font's face fixed status
//TTF_Font *font;

if(TTF_FontFaceIsFixedWidth(font))
    printf("The font is fixed width.\n");
else
    printf("The font is not fixed width.\n");

See Also:
3.3.14 TTF_FontFaces,
3.3.16 TTF_FontFaceFamilyName,
3.3.17 TTF_FontFaceStyleName,
3.3.19 TTF_GlyphMetrics

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_FontFaceFamilyName

3.3.16 TTF_FontFaceFamilyName

char * TTF_FontFaceFamilyName(const TTF_Font *font)

font
The loaded font to get the current face family name of.

Get the current font face family name from the loaded font. This function may return a NULL pointer, in which case the information is not available.
NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The current family name of of the face of the font, or NULL perhaps.

// get the loaded font's face name
//TTF_Font *font;

char *familyname=TTF_FontFaceFamilyName(font);
if(familyname)
    printf("The family name of the face in the font is: %s\n", familyname);

See Also:
3.3.14 TTF_FontFaces,
3.3.15 TTF_FontFaceIsFixedWidth,
3.3.17 TTF_FontFaceStyleName

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_FontFaceStyleName

3.3.17 TTF_FontFaceStyleName

char * TTF_FontFaceStyleName(const TTF_Font *font)

font
The loaded font to get the current face style name of.

Get the current font face style name from the loaded font. This function may return a NULL pointer, in which case the information is not available.
NOTE: Passing a NULL font into this function will cause a segfault.

Returns: The current style name of of the face of the font, or NULL perhaps.

// get the loaded font's face style name
//TTF_Font *font;

char *stylename=TTF_FontFaceStyleName(font);
if(stylename)
    printf("The name of the face in the font is: %s\n", stylename);

See Also:
3.3.14 TTF_FontFaces,
3.3.15 TTF_FontFaceIsFixedWidth,
3.3.16 TTF_FontFaceFamilyName

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_GlyphIsProvided

3.3.18 TTF_GlyphIsProvided

int TTF_GlyphIsProvided(const TTF_Font *font, Uint16 ch)

font
The loaded font to get the glyph availability in.
ch
the unicode character to test glyph availability of.

Get the status of the availability of the glyph for ch from the loaded font.
NOTE: Passing a NULL font into this function will cause a segfault.

Returns: the index of the glyph for ch in font, or 0 for an undefined character code.

// check for a glyph for 'g' in the loaded font
//TTF_Font *font;

int index=TTF_GlyphIsProvided(font,'g');
if(!index)
    printf("There is no 'g' in the loaded font!\n");

See Also:
3.3.19 TTF_GlyphMetrics

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_GlyphMetrics

3.3.19 TTF_GlyphMetrics

int TTF_GlyphMetrics(TTF_Font *font, Uint16 ch, int *minx, int *maxx, int *miny, int *maxy, int *advance)

font
The loaded font from which to get the glyph metrics of ch.
ch
the UNICODE char to get the glyph metrics for.
minx
pointer to int to store the returned minimum X offset into, or NULL when no return value desired.
maxx
pointer to int to store the returned maximum X offset into, or NULL when no return value desired.
miny
pointer to int to store the returned minimum Y offset into, or NULL when no return value desired.
maxy
pointer to int to store the returned maximum Y offset into, or NULL when no return value desired.
advance
pointer to int to store the returned advance offset into, or NULL when no return value desired.

Get desired glyph metrics of the UNICODE chargiven in ch from the loaded font.
NOTE: Passing a NULL font into this function will cause a segfault.

Returns: 0 on success, with all non-NULL parameters set to the glyph metric as appropriate. -1 on errors, such as when the glyph named by ch does not exist in the font.

// get the glyph metric for the letter 'g' in a loaded font
//TTF_Font *font;
int minx,maxx,miny,maxy,advance;
if(TTF_GlyphMetrics(font,'g',&minx,&maxx,&miny,&maxy,&advance)==-1)
    printf("%s\n",TTF_GetError());
else {
    printf("minx    : %d\n",minx);
    printf("maxx    : %d\n",maxx);
    printf("miny    : %d\n",miny);
    printf("maxy    : %d\n",maxy);
    printf("advance : %d\n",advance);
}

This diagram shows the relationships between the values:

Here's how the numbers look:
TTF_FontHeight       : 53
TTF_FontAscent       : 38
TTF_FontDescent      : -14
TTF_FontLineSkip     : 55
TTF_GlyphMetrics('g'):
        minx=1
        maxx=15
        miny=-7
        maxy=15
        advance=16

We see from the Line Skip that each line of text is 55 pixels high, including spacing for this font.
The Ascent-Descent=52, so there seems to be 3 pixels worth of space between lines for this font.

Let's say we want to draw the surface of glyph 'g' (retrived via 3.4.4 TTF_RenderGlyph_Solid or a similar function), at coordinates (X,Y) for the top left corner of the desired location. Here's the math using glyph metrics:
//SDL_Surface *glyph,*screen;
SDL_Rect rect;
int minx,maxy,advance;
TTF_GlyphMetrics(font,'g',&minx,NULL,NULL,&maxy,&advance);
rect.x=X+minx;
rect.y=Y+TTF_FontAscent(font)-maxy;
SDL_BlitSurface(glyph,NULL,screen,&rect);
X+=advance;

Let's say we want to draw the same glyph at coordinates (X,Y) for the origin (on the baseline) of the desired location. Here's the math using glyph metrics:
//TTF_Font *font;
//SDL_Surface *glyph,*screen;
SDL_Rect rect;
int minx,maxy,advance;
TTF_GlyphMetrics(font,'g',&minx,NULL,NULL,&maxy,&advance);
rect.x=X+minx;
rect.y=Y-maxy;
SDL_BlitSurface(glyph,NULL,screen,&rect);
X+=advance;

NOTE: The only difference between these example is the +TTF_FontAscent(font) used in the top-left corner algorithm. NOTE: These examples assume that 'g' is present in the font!
NOTE: In practice you may want to also subtract TTF_GetFontOutline(font) from your X and Y coordinates to keep the glyphs in the same place no matter what outline size is set.

See the web page at The FreeType2 Documentation Tutorial for more.

Any glyph based rendering calculations will not result in accurate kerning between adjacent glyphs. (see section Kerning)

See Also:
3.3.10 TTF_FontHeight,
3.3.11 TTF_FontAscent,
3.3.12 TTF_FontDescent,
3.3.13 TTF_FontLineSkip,
3.3.20 TTF_SizeText,
3.3.21 TTF_SizeUTF8,
3.3.22 TTF_SizeUNICODE,
3.3.18 TTF_GlyphIsProvided,
3.3.4 TTF_GetFontOutline

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_SizeText

3.3.20 TTF_SizeText

int TTF_SizeText(TTF_Font *font, const char *text, int *w, int *h)

font
The loaded font to use to calculate the size of the string with.
text
The LATIN1 null terminated string to size up.
w
pointer to int in which to fill the text width, or NULL for no desired return value.
h
pointer to int in which to fill the text height, or NULL for no desired return value.

Calculate the resulting surface size of the LATIN1 encoded text rendered using font. No actual rendering is done, however correct kerning is done to get the actual width. The height returned in h is the same as you can get using 3.3.10 TTF_FontHeight.
NOTE: Passing a NULL font into this function will cause a segfault. NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: 0 on success with the ints pointed to by w and h set as appropriate, if they are not NULL. -1 is returned on errors, such as a glyph in the string not being found.

// get the width and height of a string as it would be rendered in a loaded font
//TTF_Font *font;
int w,h;
if(TTF_SizeText(font,"Hello World!",&w,&h)) {
    // perhaps print the current TTF_GetError(), the string can't be rendered...
} else {
    printf("width=%d height=%d\n",w,h);
}

See Also:
3.3.21 TTF_SizeUTF8,
3.3.22 TTF_SizeUNICODE,
3.4.1 TTF_RenderText_Solid,
3.4.5 TTF_RenderText_Shaded,
3.4.9 TTF_RenderText_Blended

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_SizeUTF8

3.3.21 TTF_SizeUTF8

int TTF_SizeUTF8(TTF_Font *font, const char *text, int *w, int *h)

font
The loaded font to use to calculate the size of the string with.
text
The UTF8 null terminated string to size up.
w
pointer to int in which to fill the text width, or NULL for no desired return value.
h
pointer to int in which to fill the text height, or NULL for no desired return value.

Calculate the resulting surface size of the UTF8 encoded text rendered using font. No actual rendering is done, however correct kerning is done to get the actual width. The height returned in h is the same as you can get using 3.3.10 TTF_FontHeight.
NOTE: Passing a NULL font into this function will cause a segfault. NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: 0 on success with the ints pointed to by w and h set as appropriate, if they are not NULL. -1 is returned on errors, such as a glyph in the string not being found.

Note that this example uses the same text as in the LATIN1 example, that is because plain ASCII is UTF8 compatible.
// get the width and height of a string as it would be rendered in a loaded font
//TTF_Font *font;
int w,h;
if(TTF_SizeUTF8(font,"Hello World!",&w,&h)) {
    // perhaps print the current TTF_GetError(), the string can't be rendered...
} else {
    printf("width=%d height=%d\n",w,h);
}

See Also:
3.3.20 TTF_SizeText,
3.3.22 TTF_SizeUNICODE,
3.4.2 TTF_RenderUTF8_Solid,
3.4.6 TTF_RenderUTF8_Shaded,
3.4.10 TTF_RenderUTF8_Blended

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_SizeUNICODE

3.3.22 TTF_SizeUNICODE

int TTF_SizeUNICODE(TTF_Font *font, const Unit16 *text, int *w, int *h)

font
The loaded font to use to calculate the size of the string with.
text
The UNICODE null terminated string to size up.
w
pointer to int in which to fill the text width, or NULL for no desired return value.
h
pointer to int in which to fill the text height, or NULL for no desired return value.

Calculate the resulting surface size of the UNICODE encoded text rendered using font. No actual rendering is done, however correct kerning is done to get the actual width. The height returned in h is the same as you can get using 3.3.10 TTF_FontHeight.
NOTE: Passing a NULL font into this function will cause a segfault. NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: 0 on success with the ints pointed to by w and h set as appropriate, if they are not NULL. -1 is returned on errors, such as a glyph in the string not being found.

// get the width and height of a string as it would be rendered in a loaded font
//TTF_Font *font;
int w,h;
Uint16 text[]={'H','e','l','l','o',' ',
               'W','o','r','l','d','!'};
if(TTF_SizeUNICODE(font,text,&w,&h)) {
    // perhaps print the current TTF_GetError(), the string can't be rendered...
} else {
    printf("width=%d height=%d\n",w,h);
}

See Also:
3.3.20 TTF_SizeText,
3.3.21 TTF_SizeUTF8,
3.4.3 TTF_RenderUNICODE_Solid,
3.4.7 TTF_RenderUNICODE_Shaded,
3.4.11 TTF_RenderUNICODE_Blended

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: Render

3.4 Render

These functions render text using a TTF_Font.
There are three modes of rendering:

Solid
Quick and Dirty
Create an 8-bit palettized surface and render the given text at fast quality with the given font and color. The pixel value of 0 is the colorkey, giving a transparent background when blitted. Pixel and colormap value 1 is set to the text foreground color. This allows you to change the color without having to render the text again. Palette index 0 is of course not drawn when blitted to another surface, since it is the colorkey, and thus transparent, though its actual color is 255 minus each of the RGB components of the foreground color. This is the fastest rendering speed of all the rendering modes. This results in no box around the text, but the text is not as smooth. The resulting surface should blit faster than the Blended one. Use this mode for FPS and other fast changing updating text displays.
Shaded
Slow and Nice, but with a Solid Box
Create an 8-bit palettized surface and render the given text at high quality with the given font and colors. The 0 pixel value is background, while other pixels have varying degrees of the foreground color from the background color. This results in a box of the background color around the text in the foreground color. The text is antialiased. This will render slower than Solid, but in about the same time as Blended mode. The resulting surface should blit as fast as Solid, once it is made. Use this when you need nice text, and can live with a box.
Blended
Slow Slow Slow, but Ultra Nice over another image
Create a 32-bit ARGB surface and render the given text at high quality, using alpha blending to dither the font with the given color. This results in a surface with alpha transparency, so you don't have a solid colored box around the text. The text is antialiased. This will render slower than Solid, but in about the same time as Shaded mode. The resulting surface will blit slower than if you had used Solid or Shaded. Use this when you want high quality, and the text isn't changing too fast.

Solid
3.4.1 TTF_RenderText_Solid | Draw LATIN1 text in solid mode
3.4.2 TTF_RenderUTF8_Solid | Draw UTF8 text in solid mode
3.4.3 TTF_RenderUNICODE_Solid | Draw UNICODE text in solid mode
3.4.4 TTF_RenderGlyph_Solid | Draw a UNICODE glyph in solid mode
Shaded
3.4.5 TTF_RenderText_Shaded | Draw LATIN1 text in shaded mode
3.4.6 TTF_RenderUTF8_Shaded | Draw UTF8 text in shaded mode
3.4.7 TTF_RenderUNICODE_Shaded | Draw UNICODE text in shaded mode
3.4.8 TTF_RenderGlyph_Shaded | Draw a UNICODE glyph in shaded mode
Blended
3.4.9 TTF_RenderText_Blended | Draw LATIN1 text in blended mode
3.4.10 TTF_RenderUTF8_Blended | Draw UTF8 text in blended mode
3.4.11 TTF_RenderUNICODE_Blended | Draw UNICODE text in blended mode
3.4.12 TTF_RenderGlyph_Blended | Draw a UNICODE glyph in blended mode

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_RenderText_Solid

3.4.1 TTF_RenderText_Solid

SDL_Surface *TTF_RenderText_Solid(TTF_Font *font, const char *text, SDL_Color fg)

font
Font to render the text with. A NULL pointer is not checked.
text
The LATIN1 null terminated string to render.
fg
The color to render the text in. This becomes colormap index 1.

Render the LATIN1 encoded text using font with fg color onto a new surface, using the Solid mode (see section Solid). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

// Render some text in solid black to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0};
SDL_Surface *text_surface;
if(!(text_surface=TTF_RenderText_Solid(font,"Hello World!",color))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.20 TTF_SizeText,
3.4.2 TTF_RenderUTF8_Solid,
3.4.3 TTF_RenderUNICODE_Solid,
3.4.4 TTF_RenderGlyph_Solid,
3.4.5 TTF_RenderText_Shaded,
3.4.9 TTF_RenderText_Blended

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_RenderUTF8_Solid

3.4.2 TTF_RenderUTF8_Solid

SDL_Surface *TTF_RenderUTF8_Solid(TTF_Font *font, const char *text, SDL_Color fg)

font
Font to render the text with. A NULL pointer is not checked.
text
The UTF8 null terminated string to render.
fg
The color to render the text in. This becomes colormap index 1.

Render the UTF8 encoded text using font with fg color onto a new surface, using the Solid mode (see section Solid). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

Note that this example uses the same text as in the LATIN1 example, that is because plain ASCII is UTF8 compatible.
// Render some UTF8 text in solid black to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0};
SDL_Surface *text_surface;
if(!(text_surface=TTF_RenderUTF8_Solid(font,"Hello World!",color))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.21 TTF_SizeUTF8,
3.4.1 TTF_RenderText_Solid,
3.4.3 TTF_RenderUNICODE_Solid,
3.4.4 TTF_RenderGlyph_Solid,
3.4.6 TTF_RenderUTF8_Shaded,
3.4.10 TTF_RenderUTF8_Blended

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_RenderUNICODE_Solid

3.4.3 TTF_RenderUNICODE_Solid

SDL_Surface *TTF_RenderUNICODE_Solid(TTF_Font *font, const Uint16 *text, SDL_Color fg)

font
Font to render the text with. A NULL pointer is not checked.
text
The UNICODE null terminated string to render.
fg
The color to render the text in. This becomes colormap index 1.

Render the UNICODE encoded text using font with fg color onto a new surface, using the Solid mode (see section Solid). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

// Render some UNICODE text in solid black to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0};
SDL_Surface *text_surface;
Uint16 text[]={'H','e','l','l','o',' ',
               'W','o','r','l','d','!'};
if(!(text_surface=TTF_RenderUNICODE_Solid(font,text,color))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.22 TTF_SizeUNICODE,
3.4.1 TTF_RenderText_Solid,
3.4.2 TTF_RenderUTF8_Solid,
3.4.4 TTF_RenderGlyph_Solid,
3.4.7 TTF_RenderUNICODE_Shaded,
3.4.11 TTF_RenderUNICODE_Blended

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_RenderGlyph_Solid

3.4.4 TTF_RenderGlyph_Solid

SDL_Surface *TTF_RenderGlyph_Solid(TTF_Font *font, Uint16 ch, SDL_Color fg)

font
Font to render the glyph with. A NULL pointer is not checked.
text
The UNICODE character to render.
fg
The color to render the glyph in. This becomes colormap index 1.

Render the glyph for the UNICODE ch using font with fg color onto a new surface, using the Solid mode (see section Solid). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors, such as when the glyph not available in the font.

// Render and cache all printable ASCII characters in solid black
//SDL_Surface *screen;
SDL_Color color={0,0,0};
SDL_Surface *glyph_cache[128-20];
Uint16 ch;
for(ch=20; ch<128; ++ch)
    glyph_cache[ch-20]=TTF_RenderGlyph_Solid(font,ch,color);
Combined with a cache of the glyph metrics (minx, miny, and advance), you might make a fast text rendering routine that prints directly to the screen, but with inaccurate kerning. (see section Kerning)

See Also:
3.4.8 TTF_RenderGlyph_Shaded,
3.4.12 TTF_RenderGlyph_Blended,
3.4.1 TTF_RenderText_Solid,
3.4.2 TTF_RenderUTF8_Solid,
3.4.4 TTF_RenderGlyph_Solid,
3.3.19 TTF_GlyphMetrics

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_RenderText_Shaded

3.4.5 TTF_RenderText_Shaded

SDL_Surface *TTF_RenderText_Shaded(TTF_Font *font, const char *text, SDL_Color fg, SDL_Color bg)

font
Font to render the text with. A NULL pointer is not checked.
text
The LATIN1 null terminated string to render.
fg
The color to render the text in. This becomes colormap index 1.
bg
The color to render the background box in. This becomes colormap index 0.

Render the LATIN1 encoded text using font with fg color onto a new surface filled with the bg color, using the Shaded mode (see section Shaded). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

// Render some text in shaded black on white to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0}, bgcolor={0xff,0xff,0xff};
SDL_Surface *text_surface;
if(!(text_surface=TTF_RenderText_Shaded(font,"Hello World!",color,bgcolor))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.20 TTF_SizeText,
3.4.6 TTF_RenderUTF8_Shaded,
3.4.7 TTF_RenderUNICODE_Shaded,
3.4.8 TTF_RenderGlyph_Shaded,
3.4.1 TTF_RenderText_Solid,
3.4.9 TTF_RenderText_Blended

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_RenderUTF8_Shaded

3.4.6 TTF_RenderUTF8_Shaded

SDL_Surface *TTF_RenderUTF8_Shaded(TTF_Font *font, const char *text, SDL_Color fg, SDL_Color bg)

font
Font to render the text with. A NULL pointer is not checked.
text
The UTF8 null terminated string to render.
fg
The color to render the text in. This becomes colormap index 1.
bg
The color to render the background box in. This becomes colormap index 0.

Render the UTF8 encoded text using font with fg color onto a new surface filled with the bg color, using the Shaded mode (see section Shaded). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

Note that this example uses the same text as in the LATIN1 example, that is because plain ASCII is UTF8 compatible.
// Render some UTF8 text in shaded black on white to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0}, bgcolor={0xff,0xff,0xff};
SDL_Surface *text_surface;
if(!(text_surface=TTF_RenderUTF8_Shaded(font,"Hello World!",color,bgcolor))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.21 TTF_SizeUTF8,
3.4.5 TTF_RenderText_Shaded,
3.4.7 TTF_RenderUNICODE_Shaded,
3.4.8 TTF_RenderGlyph_Shaded,
3.4.2 TTF_RenderUTF8_Solid,
3.4.10 TTF_RenderUTF8_Blended

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_RenderUNICODE_Shaded

3.4.7 TTF_RenderUNICODE_Shaded

SDL_Surface *TTF_RenderUNICODE_Shaded(TTF_Font *font, const Uint16 *text, SDL_Color fg, SDL_Color bg)

font
Font to render the text with. A NULL pointer is not checked.
text
The UNICODE null terminated string to render.
fg
The color to render the text in. This becomes colormap index 1.
bg
The color to render the background box in. This becomes colormap index 0.

Render the UNICODE encoded text using font with fg color onto a new surface filled with the bg color, using the Shaded mode (see section Shaded). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

// Render some UNICODE text in shaded black on white to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0}, bgcolor={0xff,0xff,0xff};
SDL_Surface *text_surface;
Uint16 text[]={'H','e','l','l','o',' ',
               'W','o','r','l','d','!'};
if(!(text_surface=TTF_RenderUNICODE_Shaded(font,text,color,bgcolor))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.22 TTF_SizeUNICODE,
3.4.5 TTF_RenderText_Shaded,
3.4.6 TTF_RenderUTF8_Shaded,
3.4.8 TTF_RenderGlyph_Shaded,
3.4.3 TTF_RenderUNICODE_Solid,
3.4.11 TTF_RenderUNICODE_Blended

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_RenderGlyph_Shaded

3.4.8 TTF_RenderGlyph_Shaded

SDL_Surface *TTF_RenderGlyph_Shaded(TTF_Font *font, Uint16 ch, SDL_Color fg, SDL_Color bg)

font
Font to render the glyph with. A NULL pointer is not checked.
text
The UNICODE character to render.
fg
The color to render the glyph in. This becomes colormap index 1.
bg
The color to render the background box in. This becomes colormap index 0.

Render the glyph for the UNICODE ch using font with fg color onto a new surface filled with the bg color, using the Shaded mode (see section Shaded). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors, such as when the glyph not available in the font.

// Render and cache all printable ASCII characters in shaded black on white
//SDL_Surface *screen;
SDL_Color color={0,0,0}, bgcolor={0xff,0xff,0xff};
SDL_Surface *glyph_cache[128-20];
Uint16 ch;
for(ch=20; ch<128; ++ch)
    glyph_cache[ch-20]=TTF_RenderGlyph_Shaded(font,ch,color,bgcolor);
Combined with a cache of the glyph metrics (minx, miny, and advance), you might make a fast text rendering routine that prints directly to the screen, but with inaccurate kerning. (see section Kerning)

See Also:
3.4.4 TTF_RenderGlyph_Solid,
3.4.12 TTF_RenderGlyph_Blended,
3.4.5 TTF_RenderText_Shaded,
3.4.6 TTF_RenderUTF8_Shaded,
3.4.8 TTF_RenderGlyph_Shaded,
3.3.19 TTF_GlyphMetrics

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_RenderText_Blended

3.4.9 TTF_RenderText_Blended

SDL_Surface *TTF_RenderText_Blended(TTF_Font *font, const char *text, SDL_Color fg)

font
Font to render the text with. A NULL pointer is not checked.
text
The LATIN1 null terminated string to render.
fg
The color to render the text in. Pixels are blended between transparent and this color to draw the antialiased glyphs.

Render the LATIN1 encoded text using font with fg color onto a new surface, using the Blended mode (see section Blended). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

// Render some text in blended black to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0};
SDL_Surface *text_surface;
if(!(text_surface=TTF_RenderText_Blended(font,"Hello World!",color))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.20 TTF_SizeText,
3.4.10 TTF_RenderUTF8_Blended,
3.4.11 TTF_RenderUNICODE_Blended,
3.4.12 TTF_RenderGlyph_Blended,
3.4.1 TTF_RenderText_Solid,
3.4.5 TTF_RenderText_Shaded

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_RenderUTF8_Blended

3.4.10 TTF_RenderUTF8_Blended

SDL_Surface *TTF_RenderUTF8_Blended(TTF_Font *font, const char *text, SDL_Color fg)

font
Font to render the text with. A NULL pointer is not checked.
text
The UTF8 null terminated string to render.
fg
The color to render the text in. Pixels are blended between transparent and this color to draw the antialiased glyphs.

Render the UTF8 encoded text using font with fg color onto a new surface, using the Blended mode (see section Blended). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

Note that this example uses the same text as in the LATIN1 example, that is because plain ASCII is UTF8 compatible.
// Render some UTF8 text in blended black to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0};
SDL_Surface *text_surface;
if(!(text_surface=TTF_RenderUTF8_Blended(font,"Hello World!",color))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.21 TTF_SizeUTF8,
3.4.9 TTF_RenderText_Blended,
3.4.11 TTF_RenderUNICODE_Blended,
3.4.12 TTF_RenderGlyph_Blended,
3.4.2 TTF_RenderUTF8_Solid,
3.4.6 TTF_RenderUTF8_Shaded

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_RenderUNICODE_Blended

3.4.11 TTF_RenderUNICODE_Blended

SDL_Surface *TTF_RenderUNICODE_Blended(TTF_Font *font, const Uint16 *text, SDL_Color fg)

font
Font to render the text with. A NULL pointer is not checked.
text
The UNICODE null terminated string to render.
fg
The color to render the text in. Pixels are blended between transparent and this color to draw the antialiased glyphs.

Render the UNICODE encoded text using font with fg color onto a new surface, using the Blended mode (see section Blended). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.
NOTE: Passing a NULL text into this function will result in undefined behavior.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors.

// Render some UNICODE text in blended black to a new surface
// then blit to the upper left of the screen
// then free the text surface
//SDL_Surface *screen;
SDL_Color color={0,0,0};
SDL_Surface *text_surface;
Uint16 text[]={'H','e','l','l','o',' ',
               'W','o','r','l','d','!'};
if(!(text_surface=TTF_RenderUNICODE_Blended(font,text,color))) {
    //handle error here, perhaps print TTF_GetError at least
} else {
    SDL_BlitSurface(text_surface,NULL,screen,NULL);
    //perhaps we can reuse it, but I assume not for simplicity.
    SDL_FreeSurface(text_surface);
}

See Also:
3.3.22 TTF_SizeUNICODE,
3.4.9 TTF_RenderText_Blended,
3.4.10 TTF_RenderUTF8_Blended,
3.4.12 TTF_RenderGlyph_Blended,
3.4.3 TTF_RenderUNICODE_Solid,
3.4.7 TTF_RenderUNICODE_Shaded

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_RenderGlyph_Blended

3.4.12 TTF_RenderGlyph_Blended

SDL_Surface *TTF_RenderGlyph_Blended(TTF_Font *font, Uint16 ch, SDL_Color fg)

font
Font to render the glyph with. A NULL pointer is not checked.
text
The UNICODE character to render.
fg
The color to render the glyph in. Pixels are blended between transparent and this color to draw the antialiased glyph.

Render the glyph for the UNICODE ch using font with fg color onto a new surface, using the Blended mode (see section Blended). The caller (you!) is responsible for freeing any returned surface.

NOTE: Passing a NULL font into this function will cause a segfault.

Returns: a pointer to a new SDL_Surface. NULL is returned on errors, such as when the glyph not available in the font.

// Render and cache all printable ASCII characters in blended black
//SDL_Surface *screen;
SDL_Color color={0,0,0};
SDL_Surface *glyph_cache[128-20];
Uint16 ch;
for(ch=20; ch<128; ++ch)
    glyph_cache[ch-20]=TTF_RenderGlyph_Blended(font,ch,color);
Combined with a cache of the glyph metrics (minx, miny, and advance), you might make a fast text rendering routine that prints directly to the screen, but with inaccurate kerning. (see section Kerning)

See Also:
3.4.4 TTF_RenderGlyph_Solid,
3.4.8 TTF_RenderGlyph_Shaded,
3.4.9 TTF_RenderText_Blended,
3.4.10 TTF_RenderUTF8_Blended,
3.4.12 TTF_RenderGlyph_Blended,
3.3.19 TTF_GlyphMetrics

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: Types

4. Types

These types are defined and used by the SDL_ttf API.

4.1 TTF_Font The opaque holder of a loaded font

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: TTF_Font

4.1 TTF_Font

typedef struct _TTF_Font TTF_Font;

The opaque holder of a loaded font. You should always be using a pointer of this type, as in TTF_Font*, and not just plain TTF_Font. This stores the font data in a struct that is exposed only by using the API functions to get information. You should not try to access the struct data directly, since the struct may change in different versions of the API, and thus your program would be unreliable.

See Also:
3.2 Management

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: Defines

5. Defines

TTF_MAJOR_VERSION
2
SDL_ttf library major number at compilation time.
TTF_MINOR_VERSION
0
SDL_ttf library minor number at compilation time.
TTF_PATCHLEVEL
10
SDL_ttf library patch level at compilation time.
UNICODE_BOM_NATIVE
0xFEFF
This allows you to switch byte-order of UNICODE text data to native order, meaning the mode of your CPU. This is meant to be used in a UNICODE string that you are using with the SDL_ttf API.
UNICODE_BOM_SWAPPED
0xFFFE
This allows you to switch byte-order of UNICODE text data to swapped order, meaning the reversed mode of your CPU. So if your CPU is LSB, then the data will be interpretted as MSB. This is meant to be used in a UNICODE string that you are using with the SDL_ttf API.
TTF_STYLE_NORMAL
0x00
Used to indicate regular, normal, plain rendering style.
TTF_STYLE_BOLD
0x01
Used to indicate bold rendering style. This is used in a bitmask along with other styles.
TTF_STYLE_ITALIC
0x02
Used to indicate italicized rendering style. This is used in a bitmask along with other styles.
TTF_STYLE_UNDERLINE
0x04
Used to indicate underlined rendering style. This is used in a bitmask along with other styles.
TTF_STYLE_STRIKETHROUGH
0x08
Used to indicate strikethrough rendering style. This is used in a bitmask along with other styles.
TTF_HINTING_NORMAL
0
Used to indicate set hinting type to normal.
This corresponds to the default hinting algorithm, optimized for standard gray-level rendering
TTF_HINTING_LIGHT
0
Used to indicate set hinting type to light.
A lighter hinting algorithm for non-monochrome modes. Many generated glyphs are more fuzzy but better resemble its original shape. A bit like rendering on Mac OS X.
TTF_HINTING_MONO
0
Used to indicate set hinting type to monochrome.
Strong hinting algorithm that should only be used for monochrome output. The result is probably unpleasant if the glyph is rendered in non-monochrome modes.
TTF_HINTING_NONE
0
Used to indicate set hinting type to none.
No hinting is used so the font may become very blurry or messy at smaller sizes.

See Also:
6. Glossary,

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: Glossary

6. Glossary

Byte Order This all has to do with how data larger than a byte is actually stored in memory. The CPU expects 16bit and 32bit, and larger, data to be ordered in one of the two ways listed below. SDL has macros which you can use to detemine which endianness your program will be using.

Big-Endian(MSB) means the most significant byte comes first in storage. Sparc and Motorola 68k based chips are MSB ordered.
(SDL defines this as SDL_BYTEORDER==SDL_BIG_ENDIAN)

Little-Endian(LSB) is stored in the opposite order, with the least significant byte first in memory. Intel and AMD are two LSB machines.
(SDL defines this as SDL_BYTEORDER==SDL_LIL_ENDIAN)

LATIN1 Latin-1 is an extension of ASCII, where ASCII only defines characters 0 through 127. Latin-1 continues and adds more common international symbols to define through character 255.

ISO 8859-1 (Latin-1) Unicode Table (pdf)

Hinting Font hinting is the use of mathematical instructions to adjust the display of an outline font so that it lines up with a rasterized grid. At small screen sizes, with or without antialiasing, hinting is critical for producing a clear, legible text for human readers.

Kerning Kerning is the process of spacing adjacent characters apart depending on the actual two adjacent characters. This allows some characters to be closer to each other than others. When kerning is not used, such as when using the glyph metrics advance value, the characters will be spaced out at a constant size that accomodates all pairs of adjacent characters. This would be the maximum space between characters needed. There's currently no method to retrieve the kerning for a pair of characters from SDL_ttf, However correct kerning will be applied when a string of text is rendered instead of individual glyphs.

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: Index

Index

Jump to: A B H K L M R S T U

 | Index Entry | Section
A |  |
 | ASCII | 6. Glossary
B |  |
 | Big-Endian | 6. Glossary
 | Blended | 3.4 Render
 | Byte Order | 6. Glossary
H |  |
 | Hinting | 6. Glossary
K |  |
 | Kerning | 6. Glossary
L |  |
 | LATIN1 | 6. Glossary
 | Little-Endian | 6. Glossary
 | LSB | 6. Glossary
M |  |
 | MSB | 6. Glossary
R |  |
 | README | 1. Overview
S |  |
 | sdl-config | 2.2 Compiling
 | SDL_TTF_MAJOR_VERSION | 5. Defines
 | SDL_TTF_MINOR_VERSION | 5. Defines
 | SDL_TTF_PATCHLEVEL | 5. Defines
 | SDL_TTF_VERSION | 3.1.1 TTF_Linked_Version
 | Shaded | 3.4 Render
 | Solid | 3.4 Render
T |  |
 | TTF_ByteSwappedUNICODE | 3.3.1 TTF_ByteSwappedUNICODE
 | TTF_CloseFont | 3.2.5 TTF_CloseFont
 | TTF_Font | 3.2 Management
 | TTF_Font | 3.3 Attributes
 | TTF_Font | 3.4 Render
 | TTF_Font | 4.1 TTF_Font
 | TTF_FontAscent | 3.3.11 TTF_FontAscent
 | TTF_FontDescent | 3.3.12 TTF_FontDescent
 | TTF_FontFaceFamilyName | 3.3.16 TTF_FontFaceFamilyName
 | TTF_FontFaceIsFixedWidth | 3.3.15 TTF_FontFaceIsFixedWidth
 | TTF_FontFaces | 3.3.14 TTF_FontFaces
 | TTF_FontFaceStyleName | 3.3.17 TTF_FontFaceStyleName
 | TTF_FontHeight | 3.3.10 TTF_FontHeight
 | TTF_FontLineSkip | 3.3.13 TTF_FontLineSkip
 | TTF_GetError | 3.1.6 TTF_GetError
 | TTF_GetFontHinting | 3.3.6 TTF_GetFontHinting
 | TTF_GetFontKerning | 3.3.8 TTF_GetFontKerning
 | TTF_GetFontOutline | 3.3.4 TTF_GetFontOutline
 | TTF_GetFontStyle | 3.3.2 TTF_GetFontStyle
 | TTF_GlyphIsProvided | 3.3.18 TTF_GlyphIsProvided
 | TTF_GlyphMetrics | 3.3.19 TTF_GlyphMetrics
 | TTF_HINTING_LIGHT | 5. Defines
 | TTF_HINTING_MONO | 5. Defines
 | TTF_HINTING_NONE | 5. Defines
 | TTF_HINTING_NORMAL | 5. Defines
 | TTF_Init | 3.1.2 TTF_Init
 | TTF_Linked_Version | 3.1.1 TTF_Linked_Version
 | TTF_OpenFont | 3.2.1 TTF_OpenFont
 | TTF_OpenFontIndex | 3.2.3 TTF_OpenFontIndex
 | TTF_OpenFontIndexRW | 3.2.4 TTF_OpenFontIndexRW
 | TTF_OpenFontRW | 3.2.2 TTF_OpenFontRW
 | TTF_Quit | 3.1.4 TTF_Quit
 | TTF_RenderGlyph_Blended | 3.4.12 TTF_RenderGlyph_Blended
 | TTF_RenderGlyph_Shaded | 3.4.8 TTF_RenderGlyph_Shaded
 | TTF_RenderGlyph_Solid | 3.4.4 TTF_RenderGlyph_Solid
 | TTF_RenderText_Blended | 3.4.9 TTF_RenderText_Blended
 | TTF_RenderText_Shaded | 3.4.5 TTF_RenderText_Shaded
 | TTF_RenderText_Solid | 3.4.1 TTF_RenderText_Solid
 | TTF_RenderUNICODE_Blended | 3.4.11 TTF_RenderUNICODE_Blended
 | TTF_RenderUNICODE_Shaded | 3.4.7 TTF_RenderUNICODE_Shaded
 | TTF_RenderUNICODE_Solid | 3.4.3 TTF_RenderUNICODE_Solid
 | TTF_RenderUTF8_Blended | 3.4.10 TTF_RenderUTF8_Blended
 | TTF_RenderUTF8_Shaded | 3.4.6 TTF_RenderUTF8_Shaded
 | TTF_RenderUTF8_Solid | 3.4.2 TTF_RenderUTF8_Solid
 | TTF_SetError | 3.1.5 TTF_SetError
 | TTF_SetFontHinting | 3.3.7 TTF_SetFontHinting
 | TTF_SetFontKerning | 3.3.9 TTF_SetFontKerning
 | TTF_SetFontOutline | 3.3.5 TTF_SetFontOutline
 | TTF_SetFontStyle | 3.3.3 TTF_SetFontStyle
 | TTF_SizeText | 3.3.20 TTF_SizeText
 | TTF_SizeUNICODE | 3.3.22 TTF_SizeUNICODE
 | TTF_SizeUTF8 | 3.3.21 TTF_SizeUTF8
 | TTF_STYLE_BOLD | 5. Defines
 | TTF_STYLE_ITALIC | 5. Defines
 | TTF_STYLE_NORMAL | 5. Defines
 | TTF_STYLE_STRIKETHROUGH | 5. Defines
 | TTF_STYLE_UNDERLINE | 5. Defines
 | TTF_WasInit | 3.1.3 TTF_WasInit
U |  |
 | UNICODE_BOM_NATIVE | 5. Defines
 | UNICODE_BOM_SWAPPED | 5. Defines

Jump to: A B H K L M R S T U

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.7: Mix_FadeOutMusic

3.5.14 Mix_FadeOutMusic

int Mix_FadeOutMusic(int ms)

ms
Milliseconds of time that the fade-out effect should take to go to silence, starting now.

Gradually fade out the music over ms milliseconds starting from now. The music will be halted after the fade out is completed. Only when music is playing and not fading already are set to fade out, including paused channels. Any callback set by Mix_HookMusicFinished will be called when the music finishes fading out.

Returns: 1 on success, 0 on failure.

// fade out music to finish 3 seconds from now
while(!Mix_FadeOutMusic(3000) && Mix_PlayingMusic()) {
    // wait for any fades to complete
    SDL_Delay(100);
}

See Also:
3.5.13 Mix_HaltMusic, 3.5.19 Mix_FadingMusic, 3.5.17 Mix_PlayingMusic, 3.5.15 Mix_HookMusicFinished

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_HookMusicFinished

3.5.15 Mix_HookMusicFinished

void Mix_HookMusicFinished(void (*music_finished)())

music_finished
Function pointer to a void function().
NULL will remove the hook.

This sets up a function to be called when music playback is halted. Any time music stops, the music_finished function will be called. Call with NULL to remove the callback.
NOTE: NEVER call SDL_Mixer functions, nor SDL_LockAudio, from a callback function.

// make a music finished function
void musicFinished()
{
    printf("Music stopped.\n");
}
...
// use musicFinished for when music stops
Mix_HookMusicFinished(musicFinished);

See Also:
3.5.13 Mix_HaltMusic, 3.5.14 Mix_FadeOutMusic

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_GetMusicType

3.5.16 Mix_GetMusicType

Mix_MusicType Mix_GetMusicType(const Mix_Music *music)

music
The music to get the type of.
NULL will get the currently playing music type.

Tells you the file format encoding of the music. This may be handy when used with Mix_SetMusicPosition, and other music functions that vary based on the type of music being played. If you want to know the type of music currently being played, pass in NULL to music.

Returns: The type of music or if music is NULL then the currently playing music type, otherwise MUS_NONE if no music is playing.

// print the type of music currently playing
switch(Mix_GetMusicType(NULL))
{
    case MUS_NONE:
    MUS_CMD:
        printf("Command based music is playing.\n");
        break;
    MUS_WAV:
        printf("WAVE/RIFF music is playing.\n");
        break;
    MUS_MOD:
        printf("MOD music is playing.\n");
        break;
    MUS_MID:
        printf("MIDI music is playing.\n");
        break;
    MUS_OGG:
        printf("OGG music is playing.\n");
        break;
    MUS_MP3:
        printf("MP3 music is playing.\n");
        break;
    default:
        printf("Unknown music is playing.\n");
        break;
}

See Also:
4.3 Mix_MusicType, 3.6.7 Mix_SetPosition

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_PlayingMusic

3.5.17 Mix_PlayingMusic

int Mix_PlayingMusic()

Tells you if music is actively playing, or not.
Note: Does not check if the channel has been paused.

Returns: Zero if the music is not playing, or 1 if it is playing.

// check if music is playing
printf("music is%s playing.\n", Mix_PlayingMusic()?"":" not");

See Also:
3.5.18 Mix_PausedMusic, 3.5.19 Mix_FadingMusic, 3.5.3 Mix_PlayMusic

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_PausedMusic

3.5.18 Mix_PausedMusic

int Mix_PausedMusic()

Tells you if music is paused, or not.
Note: Does not check if the music was been halted after it was paused, which may seem a little weird.

Returns: Zero if music is not paused. 1 if it is paused.

// check the music pause status
printf("music is%s paused\n", Mix_PausedMusic()?"":" not");

See Also:
3.5.17 Mix_PlayingMusic, 3.5.8 Mix_PauseMusic, 3.5.9 Mix_ResumeMusic

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_FadingMusic

3.5.19 Mix_FadingMusic

Mix_Fading Mix_FadingMusic()

Tells you if music is fading in, out, or not at all. Does not tell you if the channel is playing anything, or paused, so you'd need to test that separately.

Returns: the fading status. Never returns an error.

// check the music fade status
switch(Mix_FadingMusic()) {
    case MIX_NO_FADING:
        printf("Not fading music.\n");
        break;
    case MIX_FADING_OUT:
        printf("Fading out music.\n");
        break;
    case MIX_FADING_IN:
        printf("Fading in music.\n");
        break;
}

See Also:
4.4 Mix_Fading, 3.5.18 Mix_PausedMusic, 3.5.17 Mix_PlayingMusic, 3.5.5 Mix_FadeInMusicPos, 3.5.14 Mix_FadeOutMusic

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_GetMusicHookData

3.5.20 Mix_GetMusicHookData

void *Mix_GetMusicHookData()

Get the arg passed into Mix_HookMusic.

Returns: the arg pointer.

// retrieve the music hook data pointer
void *data;
data=Mix_GetMusicHookData();

See Also:
3.5.6 Mix_HookMusic

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Effects

3.6 Effects

These functions are for special effects processing. Not all effects are all that special. All effects are post processing routines that are either built-in to SDL_ttf or created by you. Effects can be applied to individual channels, or to the final mixed stream which contains all the channels including music.

Registration
3.6.1 Mix_RegisterEffect | Hook a processor to a channel
3.6.2 Mix_UnregisterEffect | Unhook a processor from a channel
3.6.3 Mix_UnregisterAllEffects | Unhook all processors from a channel
3.6.4 Mix_SetPostMix | Hook in a postmix processor
Built-in Processors
3.6.5 Mix_SetPanning | Stereo panning
3.6.6 Mix_SetDistance | Distance attenuation (volume)
3.6.7 Mix_SetPosition | Panning(angular) and distance
3.6.8 Mix_SetReverseStereo | Swap stereo left and right

The built-in processors: Mix_SetPanning, Mix_SetPosition, Mix_SetDistance, and
Mix_SetReverseStereo, all look for an environment variable, MIX_EFFECTSMAXSPEED to be defined. If the environment variable is defined these processors may use more memory or reduce the quality of the effects, all for better speed.

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_RegisterEffect

3.6.1 Mix_RegisterEffect

int Mix_RegisterEffect(int chan, Mix_EffectFunc_t f, Mix_EffectDone_t d,
                       void *arg)

chan
channel number to register f and d on.
Use MIX_CHANNEL_POST to process the postmix stream.
f
The function pointer for the effects processor.
d
The function pointer for any cleanup routine to be called when the channel is done playing a sample.
This may be NULL for any processors that don't need to clean up any memory or other dynamic data.
arg
A pointer to data to pass into the f's and d's udata parameter. It is a good place to keep the state data for the processor, especially if the processor is made to handle multiple channels at the same time.
This may be NULL, depending on the processor.

Hook a processor function f into a channel for post processing effects. You may just be reading the data and displaying it, or you may be altering the stream to add an echo. Most processors also have state data that they allocate as they are in use, this would be stored in the arg pointer data space. When a processor is finished being used, any function passed into d will be called, which is when your processor should clean up the data in the arg data space.
The effects are put into a linked list, and always appended to the end, meaning they always work on previously registered effects output. Effects may be added multiple times in a row. Effects are cumulative this way.

Returns: Zero on errors, such as a nonexisting channel.

// make a passthru processor function that does nothing...
void noEffect(int chan, void *stream, int len, void *udata)
{
    // you could work with stream here...
}
...
// register noEffect as a postmix processor
if(!Mix_RegisterEffect(MIX_CHANNEL_POST, noEffect, NULL, NULL)) {
    printf("Mix_RegisterEffect: %s\n", Mix_GetError());
}

See Also:
3.6.2 Mix_UnregisterEffect, 3.6.3 Mix_UnregisterAllEffects

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_UnregisterEffect

3.6.2 Mix_UnregisterEffect

int Mix_UnregisterEffect(int channel, Mix_EffectFunc_t f)

channel
Channel number to remove f from as a post processor.
Use MIX_CHANNEL_POST for the postmix stream.
f
The function to remove from channel.

Remove the oldest (first found) registered effect function f from the effect list for channel. This only removes the first found occurance of that function, so it may need to be called multiple times if you added the same function multiple times, just stop removing when Mix_UnregisterEffect returns an error, to remove all occurances of f from a channel.
If the channel is active the registered effect will have its Mix_EffectDone_t function called, if it was specified in Mix_RegisterEffect.

Returns: Zero on errors, such as invalid channel, or effect function not registered on channel.

// unregister the noEffect from the postmix effects
// this removes all occurances of noEffect registered to the postmix
while(Mix_UnregisterEffect(MIX_CHANNEL_POST, noEffect));
// you may print Mix_GetError() if you want to check it.
// it should say "No such effect registered" after this loop.

See Also:
3.6.3 Mix_UnregisterAllEffects, 3.6.1 Mix_RegisterEffect

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_UnregisterAllEffects

3.6.3 Mix_UnregisterAllEffects

int Mix_UnregisterAllEffects(int channel)

channel
Channel to remove all effects from.
Use MIX_CHANNEL_POST for the postmix stream.

This removes all effects registered to channel. If the channel is active all the registered effects will have their Mix_EffectDone_t functions called, if they were specified in Mix_RegisterEffect.

Returns: Zero on errors, such as channel not existing.

// remove all effects from channel 0
if(!Mix_UnregisterAllEffects(0)) {
    printf("Mix_UnregisterAllEffects: %s\n", Mix_GetError());
}

See Also:
3.6.2 Mix_UnregisterEffect, 3.6.1 Mix_RegisterEffect

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_SetPostMix

3.6.4 Mix_SetPostMix

void Mix_SetPostMix(void (*mix_func)(void *udata, Uint8 *stream, int len),
                    void *arg)

mix_func
The function pointer for the postmix processor.
NULL unregisters the current postmixer.
arg
A pointer to data to pass into the mix_func's udata parameter. It is a good place to keep the state data for the processor, especially if the processor is made to handle multiple channels at the same time.
This may be NULL, depending on the processor.

Hook a processor function mix_func to the postmix stream for post processing effects. You may just be reading the data and displaying it, or you may be altering the stream to add an echo. Most processors also have state data that they allocate as they are in use, this would be stored in the arg pointer data space. This processor is never really finished, until the audio device is closed, or you pass NULL as the mix_func.
There can only be one postmix function used at a time through this method. Use Mix_RegisterEffect(MIX_CHANNEL_POST, mix_func, NULL, arg) to use multiple postmix processors.
This postmix processor is run AFTER all the registered postmixers set up by Mix_RegisterEffect.

// make a passthru processor function that does nothing...
void noEffect(void *udata, Uint8 *stream, int len)
{
    // you could work with stream here...
}
...
// register noEffect as a postmix processor
Mix_SetPostMix(noEffect, NULL);

See Also:
3.6.1 Mix_RegisterEffect

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_SetPanning

3.6.5 Mix_SetPanning

int Mix_SetPanning(int channel, Uint8 left, Uint8 right)

channel
Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream.
left
Volume for the left channel, range is 0(silence) to 255(loud)
right
Volume for the left channel, range is 0(silence) to 255(loud)

This effect will only work on stereo audio. Meaning you called Mix_OpenAudio with 2 channels (MIX_DEFAULT_CHANNELS). The easiest way to do true panning is to call Mix_SetPanning(channel, left, 254 - left); so that the total volume is correct, if you consider the maximum volume to be 127 per channel for center, or 254 max for left, this works, but about halves the effective volume.
This Function registers the effect for you, so don't try to Mix_RegisterEffect it yourself.
NOTE: Setting both left and right to 255 will unregister the effect from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.
NOTE: Using this function on a mono audio device will not register the effect, nor will it return an error status.

Returns: Zero on errors, such as bad channel, or if Mix_RegisterEffect failed.

// pan channel 1 halfway to the left
if(!Mix_SetPanning(1, 255, 127)) {
    printf("Mix_SetPanning: %s\n", Mix_GetError());
    // no panning, is it ok?
}

See Also:
3.6.7 Mix_SetPosition, 3.6.3 Mix_UnregisterAllEffects

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_SetDistance

3.6.6 Mix_SetDistance

int Mix_SetDistance(int channel, Uint8 distance)

channel
Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream.
distance
Specify the distance from the listener, from 0(close/loud) to 255(far/quiet).

This effect simulates a simple attenuation of volume due to distance. The volume never quite reaches silence, even at max distance.
NOTE: Using a distance of 0 will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.

Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect failed.

// distance channel 1 to be farthest away
if(!Mix_SetDistance(1, 255)) {
    printf("Mix_SetDistance: %s\n", Mix_GetError());
    // no distance, is it ok?
}

See Also:
3.6.7 Mix_SetPosition, 3.6.3 Mix_UnregisterAllEffects

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_SetPosition

3.6.7 Mix_SetPosition

int Mix_SetPosition(int channel, Sint16 angle, Uint8 distance)

channel
Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream.
angle
Direction in relation to forward from 0 to 360 degrees. Larger angles will be reduced to this range using angles % 360.
0 = directly in front.
90 = directly to the right.
180 = directly behind.
270 = directly to the left.
So you can see it goes clockwise starting at directly in front.
This ends up being similar in effect to Mix_SetPanning.
distance
The distance from the listener, from 0(near/loud) to 255(far/quiet).
This is the same as the Mix_SetDistance effect.

This effect emulates a simple 3D audio effect. It's not all that realistic, but it can help improve some level of realism. By giving it the angle and distance from the camera's point of view, the effect pans and attenuates volumes. If you are looking for better positional audio, using OpenAL is suggested.
NOTE: Using angle and distance of 0, will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.

Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect failed.

// set channel 2 to be behind and right, and 100 units away
if(!Mix_SetPosition(2, 135, 100)) {
    printf("Mix_SetPosition: %s\n", Mix_GetError());
    // no position effect, is it ok?
}

See Also:
3.6.5 Mix_SetPanning, 3.6.6 Mix_SetDistance, 3.6.3 Mix_UnregisterAllEffects

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_SetReverseStereo

3.6.8 Mix_SetReverseStereo

int Mix_SetReverseStereo(int channel, int flip)

channel
Channel number to register this effect on.
Use MIX_CHANNEL_POST to process the postmix stream.
flip
Must be non-zero to work, means nothing to the effect processor itself.
set to zero to unregister the effect from channel.

Simple reverse stereo, swaps left and right channel sound.
NOTE: Using a flip of 0, will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel.

Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect failed.

// set the total mixer output to be reverse stereo
if(!Mix_SetReverseStereo(MIX_CHANNEL_POST, 1)) {
    printf("Mix_SetReverseStereo: %s\n", Mix_GetError());
    // no reverse stereo, is it ok?
}

See Also:
3.6.3 Mix_UnregisterAllEffects

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Types

4. Types

These types are defined and used by the SDL_ttf API.

4.1 Mix_Chunk | The internal format for an audio chunk
4.2 Mix_Music | The internal format for a music chunk
4.3 Mix_MusicType | Music type enumerations
4.4 Mix_Fading | Fader effect type enumerations
4.5 Mix_EffectFunc_t | Special effect callback function pointer
4.6 Mix_EffectDone_t | Special effect done callback function pointer

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_Chunk

4.1 Mix_Chunk

typedef struct {
    int allocated;
    Uint8 *abuf;
    Uint32 alen;
    Uint8 volume;     /* Per-sample volume, 0-128 */
} Mix_Chunk;

allocated
a boolean indicating whether to free abuf when the chunk is freed.
0 if the memory was not allocated and thus not owned by this chunk.
1 if the memory was allocated and is thus owned by this chunk.
abuf
Pointer to the sample data, which is in the output format and sample rate.
alen
Length of abuf in bytes.
volume
0 = silent, 128 = max volume. This takes effect when mixing.

The internal format for an audio chunk. This stores the sample data, the length in bytes of that data, and the volume to use when mixing the sample.

See Also:
@ref{Mix_VolumeChunk}, 3.3.16 Mix_GetChunk, @ref{Mix_LoadWAV}, @ref{Mix_LoadWAV_RW}, @ref{Mix_FreeChunk}, 4.2 Mix_Music

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_Music

4.2 Mix_Music

typedef struct _Mix_Music Mix_Music;

This is an opaque data type used for Music data. This should always be used as a pointer. Who knows why it isn't a pointer in this typedef...

See Also:
3.5.1 Mix_LoadMUS, 3.5.2 Mix_FreeMusic, 4.1 Mix_Chunk

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_MusicType

4.3 Mix_MusicType

typedef enum {
    MUS_NONE,
    MUS_CMD,
    MUS_WAV,
    MUS_MOD,
    MUS_MID,
    MUS_OGG,
    MUS_MP3
} Mix_MusicType;

Return values from Mix_GetMusicType are of these enumerated values.
If no music is playing then MUS_NONE is returned.
If music is playing via an external command then MUS_CMD is returned.
Otherwise they are self explanatory.

See Also:
3.5.16 Mix_GetMusicType

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_Fading

4.4 Mix_Fading

typedef enum {
    MIX_NO_FADING,
    MIX_FADING_OUT,
    MIX_FADING_IN
} Mix_Fading;

Return values from Mix_FadingMusic and Mix_FadingChannel are of these enumerated values. If no fading is taking place on the queried channel or music, then MIX_NO_FADING is returned. Otherwise they are self explanatory.

See Also:
3.3.15 Mix_FadingChannel, 3.5.19 Mix_FadingMusic

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_EffectFunc_t

4.5 Mix_EffectFunc_t

typedef void (*Mix_EffectFunc_t)(int chan, void *stream, int len,
                                 void *udata);

chan
The channel number that this effect is effecting now.
MIX_CHANNEL_POST is passed in for post processing effects over the final mix.
stream
The buffer containing the current sample to process.
len
The length of stream in bytes.
udata
User data pointer that was passed in to Mix_RegisterEffect when registering this effect processor function.

This is the prototype for effect processing functions. These functions are used to apply effects processing on a sample chunk. As a channel plays a sample, the registered effect functions are called. Each effect would then read and perhaps alter the len bytes of stream. It may also be advantageous to keep the effect state in the udata, with would be setup when registering the effect function on a channel.

See Also:
3.6.1 Mix_RegisterEffect 3.6.2 Mix_UnregisterEffect

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Mix_EffectDone_t

4.6 Mix_EffectDone_t

typedef void (*Mix_EffectDone_t)(int chan, void *udata);

chan
The channel number that this effect is effecting now.
MIX_CHANNEL_POST is passed in for post processing effects over the final mix.
udata
User data pointer that was passed in to Mix_RegisterEffect when registering this effect processor function.

This is the prototype for effect processing functions. This is called when a channel has finished playing, or halted, or is deallocated. This is also called when a processor is unregistered while processing is active. At that time the effects processing function may want to reset some internal variables or free some memory. It should free memory at least, because the processor could be freed after this call.

See Also:
3.6.1 Mix_RegisterEffect 3.6.2 Mix_UnregisterEffect

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Defines

5. Defines

MIX_MAJOR_VERSION
1
SDL_ttf library major number at compilation time
MIX_MINOR_VERSION
2
SDL_ttf library minor number at compilation time
MIX_PATCHLEVEL
4
SDL_ttf library patch level at compilation time
MIX_CHANNELS
8
The default mixer has this many simultaneous mixing channels after the first call to Mix_OpenAudio.
MIX_DEFAULT_FREQUENCY
22050
Good default sample rate in Hz (samples per second) for PC sound cards.
MIX_DEFAULT_FORMAT
AUDIO_S16SYS
The suggested default is signed 16bit samples in host byte order.
MIX_DEFAULT_CHANNELS
2
Stereo sound is a good default.
MIX_MAX_VOLUME
128
Maximum value for any volume setting.
This is currently the same as SDL_MIX_MAXVOLUME.
MIX_CHANNEL_POST
-2
This is the channel number used for post processing effects.
MIX_EFFECTSMAXSPEED
"MIX_EFFECTSMAXSPEED"
A convience definition for the string name of the environment variable to define when you desire the internal effects to sacrifice quality and/or RAM for speed. The environment variable must be set (else nonexisting) before Mix_OpenAudio is called for the setting to take effect.

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Glossary

6. Glossary

Byte Order
Also known as Big-Endian. Which means the most significant byte comes first in storage. Sparc and Motorola 68k based chips are MSB ordered.
(SDL defines this as SDL_BYTEORDER==SDL_BIG_ENDIAN)

Little-Endian(LSB) is stored in the opposite order, with the least significant byte first in memory. Intel and AMD are two LSB machines.
(SDL defines this as SDL_BYTEORDER==SDL_LIL_ENDIAN)

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Index

Index

Jump to: B L M R S T

 | Index Entry | Section
B |  |
 | Big-Endian | 6. Glossary
 | Byte Order | 6. Glossary
L |  |
 | Little-Endian | 6. Glossary
 | LSB | 6. Glossary
M |  |
 | Mix_AllocateChannels | 3.3.1 Mix_AllocateChannels
 | MIX_CHANNEL_POST | 5. Defines
 | Mix_ChannelFinished | 3.3.12 Mix_ChannelFinished
 | MIX_CHANNELS | 5. Defines
 | Mix_Chunk | 4.1 Mix_Chunk
 | MIX_DEFAULT_CHANNELS | 5. Defines
 | MIX_DEFAULT_FORMAT | 5. Defines
 | MIX_DEFAULT_FREQUENCY | 5. Defines
 | Mix_EffectDone_t | 4.6 Mix_EffectDone_t
 | Mix_EffectFunc_t | 4.5 Mix_EffectFunc_t
 | MIX_EFFECTSMAXSPEED | 5. Defines
 | Mix_ExpireChannel | 3.3.10 Mix_ExpireChannel
 | Mix_FadeInChannel | 3.3.5 Mix_FadeInChannel
 | Mix_FadeInChannel | 3.4.1 Mix_ReserveChannels
 | Mix_FadeInChannelTimed | 3.3.6 Mix_FadeInChannelTimed
 | Mix_FadeInChannelTimed | 3.4.1 Mix_ReserveChannels
 | Mix_FadeInMusic | 3.5.4 Mix_FadeInMusic
 | Mix_FadeInMusicPos | 3.5.5 Mix_FadeInMusicPos
 | Mix_FadeOutChannel | 3.3.11 Mix_FadeOutChannel
 | Mix_FadeOutGroup | 3.4.8 Mix_FadeOutGroup
 | Mix_FadeOutMusic | 3.5.14 Mix_FadeOutMusic
 | Mix_Fading | 4.4 Mix_Fading
 | Mix_FadingChannel | 3.3.15 Mix_FadingChannel
 | Mix_FadingMusic | 3.5.19 Mix_FadingMusic
 | Mix_FreeMusic | 3.5.2 Mix_FreeMusic
 | Mix_GetChunk | 3.3.16 Mix_GetChunk
 | Mix_GetMusicHookData | 3.5.20 Mix_GetMusicHookData
 | Mix_GetMusicType | 3.5.16 Mix_GetMusicType
 | Mix_GroupAvailable | 3.4.5 Mix_GroupAvailable
 | Mix_GroupChannel | 3.4.2 Mix_GroupChannel
 | Mix_GroupChannels | 3.4.3 Mix_GroupChannels
 | Mix_GroupCount | 3.4.4 Mix_GroupCount
 | Mix_GroupNewer | 3.4.7 Mix_GroupNewer
 | Mix_GroupOldest | 3.4.6 Mix_GroupOldest
 | Mix_HaltChannel | 3.3.9 Mix_HaltChannel
 | Mix_HaltGroup | 3.4.9 Mix_HaltGroup
 | Mix_HaltMusic | 3.5.13 Mix_HaltMusic
 | Mix_HookMusic | 3.5.6 Mix_HookMusic
 | Mix_HookMusicFinished | 3.5.15 Mix_HookMusicFinished
 | Mix_LoadMUS | 3.5.1 Mix_LoadMUS
 | MIX_MAJOR_VERSION | 5. Defines
 | MIX_MAX_VOLUME | 5. Defines
 | MIX_MINOR_VERSION | 5. Defines
 | Mix_Music | 4.2 Mix_Music
 | Mix_MusicType | 4.3 Mix_MusicType
 | MIX_PATCHLEVEL | 5. Defines
 | Mix_Pause | 3.3.7 Mix_Pause
 | Mix_Paused | 3.3.14 Mix_Paused
 | Mix_PausedMusic | 3.5.18 Mix_PausedMusic
 | Mix_PauseMusic | 3.5.8 Mix_PauseMusic
 | Mix_PlayChannel | 3.3.3 Mix_PlayChannel
 | Mix_PlayChannel | 3.4.1 Mix_ReserveChannels
 | Mix_PlayChannelTimed | 3.3.4 Mix_PlayChannelTimed
 | Mix_PlayChannelTimed | 3.4.1 Mix_ReserveChannels
 | Mix_Playing | 3.3.13 Mix_Playing
 | Mix_PlayingMusic | 3.5.17 Mix_PlayingMusic
 | Mix_PlayMusic | 3.5.3 Mix_PlayMusic
 | Mix_RegisterEffect | 3.6.1 Mix_RegisterEffect
 | Mix_ReserveChannels | 3.4.1 Mix_ReserveChannels
 | Mix_Resume | 3.3.8 Mix_Resume
 | Mix_ResumeMusic | 3.5.9 Mix_ResumeMusic
 | Mix_RewindMusic | 3.5.10 Mix_RewindMusic
 | Mix_SetDistance | 3.6.6 Mix_SetDistance
 | Mix_SetMusicCMD | 3.5.12 Mix_SetMusicCMD
 | Mix_SetMusicPosition | 3.5.11 Mix_SetMusicPosition
 | Mix_SetPanning | 3.6.5 Mix_SetPanning
 | Mix_SetPosition | 3.6.7 Mix_SetPosition
 | Mix_SetPostMix | 3.6.4 Mix_SetPostMix
 | Mix_SetReverseStereo | 3.6.8 Mix_SetReverseStereo
 | Mix_UnregisterAllEffects | 3.6.3 Mix_UnregisterAllEffects
 | Mix_UnregisterEffect | 3.6.2 Mix_UnregisterEffect
 | Mix_Volume | 3.3.2 Mix_Volume
 | Mix_VolumeMusic | 3.5.7 Mix_VolumeMusic
 | MSB | 6. Glossary
R |  |
 | README | 1. Overview
S |  |
 | sdl-config | 2.2 Compiling
T |  |
 | TTF_CloseFont | 3.2.5 TTF_CloseFont
 | TTF_Font | 3.2 Management
 | TTF_GetError | 3.1.6 TTF_GetError
 | TTF_Init | 3.1.2 TTF_Init
 | TTF_Linked_Version | 3.1.1 TTF_Linked_Version
 | TTF_OpenFont | 3.2.1 TTF_OpenFont
 | TTF_OpenFontIndex | 3.2.3 TTF_OpenFontIndex
 | TTF_OpenFontIndexRW | 3.2.4 TTF_OpenFontIndexRW
 | TTF_OpenFontRW | 3.2.2 TTF_OpenFontRW
 | TTF_Quit | 3.1.4 TTF_Quit
 | TTF_SetError | 3.1.5 TTF_SetError
 | TTF_VERSION | 3.1.1 TTF_Linked_Version
 | TTF_WasInit | 3.1.3 TTF_WasInit

Jump to: B L M R S T

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Index

Index

Jump to: B L M R S T

 | Index Entry | Section
B |  |
 | Big-Endian | 6. Glossary
 | Byte Order | 6. Glossary
L |  |
 | Little-Endian | 6. Glossary
 | LSB | 6. Glossary
M |  |
 | Mix_AllocateChannels | 3.3.1 Mix_AllocateChannels
 | MIX_CHANNEL_POST | 5. Defines
 | Mix_ChannelFinished | 3.3.12 Mix_ChannelFinished
 | MIX_CHANNELS | 5. Defines
 | Mix_Chunk | 3.2 Samples
 | Mix_Chunk | 4.1 Mix_Chunk
 | MIX_DEFAULT_CHANNELS | 5. Defines
 | MIX_DEFAULT_FORMAT | 5. Defines
 | MIX_DEFAULT_FREQUENCY | 5. Defines
 | Mix_EffectDone_t | 4.6 Mix_EffectDone_t
 | Mix_EffectFunc_t | 4.5 Mix_EffectFunc_t
 | MIX_EFFECTSMAXSPEED | 5. Defines
 | Mix_ExpireChannel | 3.3.10 Mix_ExpireChannel
 | Mix_FadeInChannel | 3.3.5 Mix_FadeInChannel
 | Mix_FadeInChannel | 3.4.1 Mix_ReserveChannels
 | Mix_FadeInChannelTimed | 3.3.6 Mix_FadeInChannelTimed
 | Mix_FadeInChannelTimed | 3.4.1 Mix_ReserveChannels
 | Mix_FadeInMusic | 3.5.4 Mix_FadeInMusic
 | Mix_FadeInMusicPos | 3.5.5 Mix_FadeInMusicPos
 | Mix_FadeOutChannel | 3.3.11 Mix_FadeOutChannel
 | Mix_FadeOutGroup | 3.4.8 Mix_FadeOutGroup
 | Mix_FadeOutMusic | 3.5.14 Mix_FadeOutMusic
 | Mix_Fading | 4.4 Mix_Fading
 | Mix_FadingChannel | 3.3.15 Mix_FadingChannel
 | Mix_FadingMusic | 3.5.19 Mix_FadingMusic
 | Mix_FreeChunk | 3.2.6 Mix_FreeChunk
 | Mix_FreeMusic | 3.5.2 Mix_FreeMusic
 | Mix_GetChunk | 3.3.16 Mix_GetChunk
 | Mix_GetMusicHookData | 3.5.20 Mix_GetMusicHookData
 | Mix_GetMusicType | 3.5.16 Mix_GetMusicType
 | Mix_GroupAvailable | 3.4.5 Mix_GroupAvailable
 | Mix_GroupChannel | 3.4.2 Mix_GroupChannel
 | Mix_GroupChannels | 3.4.3 Mix_GroupChannels
 | Mix_GroupCount | 3.4.4 Mix_GroupCount
 | Mix_GroupNewer | 3.4.7 Mix_GroupNewer
 | Mix_GroupOldest | 3.4.6 Mix_GroupOldest
 | Mix_HaltChannel | 3.3.9 Mix_HaltChannel
 | Mix_HaltGroup | 3.4.9 Mix_HaltGroup
 | Mix_HaltMusic | 3.5.13 Mix_HaltMusic
 | Mix_HookMusic | 3.5.6 Mix_HookMusic
 | Mix_HookMusicFinished | 3.5.15 Mix_HookMusicFinished
 | Mix_LoadMUS | 3.5.1 Mix_LoadMUS
 | Mix_LoadWAV | 3.2.1 Mix_LoadWAV
 | Mix_LoadWAV_RW | 3.2.2 Mix_LoadWAV_RW
 | MIX_MAJOR_VERSION | 5. Defines
 | MIX_MAX_VOLUME | 5. Defines
 | MIX_MINOR_VERSION | 5. Defines
 | Mix_Music | 4.2 Mix_Music
 | Mix_MusicType | 4.3 Mix_MusicType
 | MIX_PATCHLEVEL | 5. Defines
 | Mix_Pause | 3.3.7 Mix_Pause
 | Mix_Paused | 3.3.14 Mix_Paused
 | Mix_PausedMusic | 3.5.18 Mix_PausedMusic
 | Mix_PauseMusic | 3.5.8 Mix_PauseMusic
 | Mix_PlayChannel | 3.3.3 Mix_PlayChannel
 | Mix_PlayChannel | 3.4.1 Mix_ReserveChannels
 | Mix_PlayChannelTimed | 3.3.4 Mix_PlayChannelTimed
 | Mix_PlayChannelTimed | 3.4.1 Mix_ReserveChannels
 | Mix_Playing | 3.3.13 Mix_Playing
 | Mix_PlayingMusic | 3.5.17 Mix_PlayingMusic
 | Mix_PlayMusic | 3.5.3 Mix_PlayMusic
 | Mix_QuickLoad_RAW | 3.2.4 Mix_QuickLoad_RAW
 | Mix_QuickLoad_WAV | 3.2.3 Mix_QuickLoad_WAV
 | Mix_RegisterEffect | 3.6.1 Mix_RegisterEffect
 | Mix_ReserveChannels | 3.4.1 Mix_ReserveChannels
 | Mix_Resume | 3.3.8 Mix_Resume
 | Mix_ResumeMusic | 3.5.9 Mix_ResumeMusic
 | Mix_RewindMusic | 3.5.10 Mix_RewindMusic
 | Mix_SetDistance | 3.6.6 Mix_SetDistance
 | Mix_SetMusicCMD | 3.5.12 Mix_SetMusicCMD
 | Mix_SetMusicPosition | 3.5.11 Mix_SetMusicPosition
 | Mix_SetPanning | 3.6.5 Mix_SetPanning
 | Mix_SetPosition | 3.6.7 Mix_SetPosition
 | Mix_SetPostMix | 3.6.4 Mix_SetPostMix
 | Mix_SetReverseStereo | 3.6.8 Mix_SetReverseStereo
 | Mix_UnregisterAllEffects | 3.6.3 Mix_UnregisterAllEffects
 | Mix_UnregisterEffect | 3.6.2 Mix_UnregisterEffect
 | Mix_Volume | 3.3.2 Mix_Volume
 | Mix_VolumeChunk | 3.2.5 Mix_VolumeChunk
 | Mix_VolumeMusic | 3.5.7 Mix_VolumeMusic
 | MSB | 6. Glossary
R |  |
 | README | 1. Overview
S |  |
 | sdl-config | 2.2 Compiling
T |  |
 | TTF_GetError | 3.1.6 TTF_GetError
 | TTF_Init | 3.1.2 TTF_Init
 | TTF_Linked_Version | 3.1.1 TTF_Linked_Version
 | TTF_Quit | 3.1.4 TTF_Quit
 | TTF_SetError | 3.1.5 TTF_SetError
 | TTF_VERSION | 3.1.1 TTF_Linked_Version
 | TTF_WasInit | 3.1.3 TTF_WasInit

Jump to: B L M R S T

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.7: Index

Index

Jump to: B L M R S

 | Index Entry | Section
B |  |
 | Big-Endian | 7. Glossary
 | Byte Order | 7. Glossary
L |  |
 | Little-Endian | 7. Glossary
 | LSB | 7. Glossary
M |  |
 | Mix_AllocateChannels | 4.3.1 Mix_AllocateChannels
 | MIX_CHANNEL_POST | 6. Defines
 | Mix_ChannelFinished | 4.3.12 Mix_ChannelFinished
 | MIX_CHANNELS | 6. Defines
 | Mix_Chunk | 4.2 Samples
 | Mix_Chunk | 5.1 Mix_Chunk
 | Mix_CloseAudio | 4.1.3 Mix_CloseAudio
 | MIX_DEFAULT_CHANNELS | 6. Defines
 | MIX_DEFAULT_FORMAT | 6. Defines
 | MIX_DEFAULT_FREQUENCY | 6. Defines
 | Mix_EffectDone_t | 5.6 Mix_EffectDone_t
 | Mix_EffectFunc_t | 5.5 Mix_EffectFunc_t
 | MIX_EFFECTSMAXSPEED | 6. Defines
 | Mix_ExpireChannel | 4.3.10 Mix_ExpireChannel
 | Mix_FadeInChannel | 4.3.5 Mix_FadeInChannel
 | Mix_FadeInChannel | 4.4.1 Mix_ReserveChannels
 | Mix_FadeInChannelTimed | 4.3.6 Mix_FadeInChannelTimed
 | Mix_FadeInChannelTimed | 4.4.1 Mix_ReserveChannels
 | Mix_FadeInMusic | 4.5.4 Mix_FadeInMusic
 | Mix_FadeInMusicPos | 4.5.5 Mix_FadeInMusicPos
 | Mix_FadeOutChannel | 4.3.11 Mix_FadeOutChannel
 | Mix_FadeOutGroup | 4.4.8 Mix_FadeOutGroup
 | Mix_FadeOutMusic | 4.5.14 Mix_FadeOutMusic
 | Mix_Fading | 5.4 Mix_Fading
 | Mix_FadingChannel | 4.3.15 Mix_FadingChannel
 | Mix_FadingMusic | 4.5.19 Mix_FadingMusic
 | Mix_FreeChunk | 4.2.6 Mix_FreeChunk
 | Mix_FreeMusic | 4.5.2 Mix_FreeMusic
 | Mix_GetChunk | 4.3.16 Mix_GetChunk
 | Mix_GetError | 4.1.5 Mix_GetError
 | Mix_GetMusicHookData | 4.5.20 Mix_GetMusicHookData
 | Mix_GetMusicType | 4.5.16 Mix_GetMusicType
 | Mix_GroupAvailable | 4.4.5 Mix_GroupAvailable
 | Mix_GroupChannel | 4.4.2 Mix_GroupChannel
 | Mix_GroupChannels | 4.4.3 Mix_GroupChannels
 | Mix_GroupCount | 4.4.4 Mix_GroupCount
 | Mix_GroupNewer | 4.4.7 Mix_GroupNewer
 | Mix_GroupOldest | 4.4.6 Mix_GroupOldest
 | Mix_HaltChannel | 4.3.9 Mix_HaltChannel
 | Mix_HaltGroup | 4.4.9 Mix_HaltGroup
 | Mix_HaltMusic | 4.5.13 Mix_HaltMusic
 | Mix_HookMusic | 4.5.6 Mix_HookMusic
 | Mix_HookMusicFinished | 4.5.15 Mix_HookMusicFinished
 | Mix_Linked_Version | 4.1.1 Mix_Linked_Version
 | Mix_LoadMUS | 4.5.1 Mix_LoadMUS
 | Mix_LoadWAV | 4.2.1 Mix_LoadWAV
 | Mix_LoadWAV_RW | 4.2.2 Mix_LoadWAV_RW
 | MIX_MAJOR_VERSION | 6. Defines
 | MIX_MAX_VOLUME | 6. Defines
 | MIX_MINOR_VERSION | 6. Defines
 | Mix_Music | 5.2 Mix_Music
 | Mix_MusicType | 5.3 Mix_MusicType
 | Mix_OpenAudio | 4.1.2 Mix_OpenAudio
 | MIX_PATCHLEVEL | 6. Defines
 | Mix_Pause | 4.3.7 Mix_Pause
 | Mix_Paused | 4.3.14 Mix_Paused
 | Mix_PausedMusic | 4.5.18 Mix_PausedMusic
 | Mix_PauseMusic | 4.5.8 Mix_PauseMusic
 | Mix_PlayChannel | 4.3.3 Mix_PlayChannel
 | Mix_PlayChannel | 4.4.1 Mix_ReserveChannels
 | Mix_PlayChannelTimed | 4.3.4 Mix_PlayChannelTimed
 | Mix_PlayChannelTimed | 4.4.1 Mix_ReserveChannels
 | Mix_Playing | 4.3.13 Mix_Playing
 | Mix_PlayingMusic | 4.5.17 Mix_PlayingMusic
 | Mix_PlayMusic | 4.5.3 Mix_PlayMusic
 | Mix_QuerySpec | 4.1.6 Mix_QuerySpec
 | Mix_QuickLoad_RAW | 4.2.4 Mix_QuickLoad_RAW
 | Mix_QuickLoad_WAV | 4.2.3 Mix_QuickLoad_WAV
 | Mix_RegisterEffect | 4.6.1 Mix_RegisterEffect
 | Mix_ReserveChannels | 4.4.1 Mix_ReserveChannels
 | Mix_Resume | 4.3.8 Mix_Resume
 | Mix_ResumeMusic | 4.5.9 Mix_ResumeMusic
 | Mix_RewindMusic | 4.5.10 Mix_RewindMusic
 | Mix_SetDistance | 4.6.6 Mix_SetDistance
 | Mix_SetError | 4.1.4 Mix_SetError
 | Mix_SetMusicCMD | 4.5.12 Mix_SetMusicCMD
 | Mix_SetMusicPosition | 4.5.11 Mix_SetMusicPosition
 | Mix_SetPanning | 4.6.5 Mix_SetPanning
 | Mix_SetPosition | 4.6.7 Mix_SetPosition
 | Mix_SetPostMix | 4.6.4 Mix_SetPostMix
 | Mix_SetReverseStereo | 4.6.8 Mix_SetReverseStereo
 | Mix_UnregisterAllEffects | 4.6.3 Mix_UnregisterAllEffects
 | Mix_UnregisterEffect | 4.6.2 Mix_UnregisterEffect
 | MIX_VERSION | 4.1.1 Mix_Linked_Version
 | Mix_Volume | 4.3.2 Mix_Volume
 | Mix_VolumeChunk | 4.2.5 Mix_VolumeChunk
 | Mix_VolumeMusic | 4.5.7 Mix_VolumeMusic
 | MSB | 7. Glossary
R |  |
 | README | 1. Overview
S |  |
 | sdl-config | 2.2 Compiling
 | SDL_AudioDriverName | 3. Conflicts
 | SDL_CloseAudio | 3. Conflicts
 | SDL_GetAudioStatus | 3. Conflicts
 | SDL_LockAudio | 3. Conflicts
 | SDL_OpenAudio | 3. Conflicts
 | SDL_PauseAudio | 3. Conflicts
 | SDL_UnlockAudio | 3. Conflicts

Jump to: B L M R S

This document was generated on August, 31 2003 using texi2html


SDL_ttf 2.0.10: About this document

About this document

This document was generated on November, 13 2009 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10: Short Table of Contents

Short Table of Contents

1. Overview
2. Getting Started
3. Functions
4. Types
5. Defines
6. Glossary
Index

This document was generated on November, 13 2009 using texi2html


SDL_ttf 2.0.10:

Content

1. Overview
2. Getting Started
3. Functions
4. Types
5. Defines
6. Glossary
Index